@omersx/bemms 0.0.0-stage → 0.1.0

package/src/lib/logger/formatters.ts

@@ -0,0 +1,159 @@
+import { LogEntry, LogLevel } from './types';
+
+const ANSI = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  magenta: '\x1b[35m',
+  gray: '\x1b[90m',
+};
+
+const LEVEL_COLORS: Record<LogLevel, string> = {
+  debug: ANSI.cyan,
+  info: ANSI.green,
+  warn: ANSI.yellow,
+  error: ANSI.red,
+  fatal: `${ANSI.bold}${ANSI.magenta}`,
+};
+
+const MAX_VALUE_LENGTH = 1000;
+
+/**
+ * Returns a JSON replacer function that safely handles circular references and BigInt values.
+ */
+function getCircularReplacer(): (key: string, value: unknown) => unknown {
+  const seen = new WeakSet();
+  return (_key: string, value: unknown) => {
+    if (typeof value === 'object' && value !== null) {
+      if (seen.has(value)) {
+        return '[Circular]';
+      }
+      seen.add(value);
+    }
+    if (typeof value === 'bigint') {
+      return value.toString();
+    }
+    return value;
+  };
+}
+
+/**
+ * Formats a Date/ISO timestamp to local HH:mm:ss.SSS representation.
+ */
+function formatTimestamp(isoString: string): string {
+  try {
+    const date = new Date(isoString);
+    if (Number.isNaN(date.getTime())) {
+      return isoString;
+    }
+    const hours = String(date.getHours()).padStart(2, '0');
+    const minutes = String(date.getMinutes()).padStart(2, '0');
+    const seconds = String(date.getSeconds()).padStart(2, '0');
+    const millis = String(date.getMilliseconds()).padStart(3, '0');
+    return `${hours}:${minutes}:${seconds}.${millis}`;
+  } catch {
+    return isoString;
+  }
+}
+
+/**
+ * Truncates string representations that exceed 1000 characters.
+ */
+function truncateValue(str: string): string {
+  if (str.length > MAX_VALUE_LENGTH) {
+    return `${str.slice(0, MAX_VALUE_LENGTH)}... [truncated]`;
+  }
+  return str;
+}
+
+/**
+ * Formats a single context property value safely, truncating if necessary.
+ */
+function formatContextValue(value: unknown): string {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (typeof value === 'string') return truncateValue(value);
+  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+    return String(value);
+  }
+  if (typeof value === 'symbol') return value.toString();
+  if (typeof value === 'function') return '[Function]';
+  if (typeof value === 'object') {
+    try {
+      const json = JSON.stringify(value, getCircularReplacer());
+      return truncateValue(json);
+    } catch {
+      return truncateValue(String(value));
+    }
+  }
+  return truncateValue(String(value));
+}
+
+/**
+ * Single-line JSON formatter for production environments (machine-parseable).
+ * Handles circular references and never throws.
+ */
+export function jsonFormatter(entry: LogEntry): string {
+  try {
+    return JSON.stringify(entry, getCircularReplacer());
+  } catch (error) {
+    return JSON.stringify({
+      level: entry.level,
+      message: entry.message,
+      timestamp: entry.timestamp,
+      module: entry.module,
+      formatError: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+/**
+ * Colorized, human-readable formatter for development environments using ANSI escape codes.
+ *
+ * Output format:
+ * HH:mm:ss.SSS LEVEL [module] message
+ *   key=value
+ *   error stack
+ */
+export function prettyFormatter(entry: LogEntry): string {
+  try {
+    const timeStr = `${ANSI.gray}${formatTimestamp(entry.timestamp)}${ANSI.reset}`;
+    const levelColor = LEVEL_COLORS[entry.level] || ANSI.reset;
+    const levelUpper = entry.level.toUpperCase().padEnd(5);
+    const levelStr = `${levelColor}${levelUpper}${ANSI.reset}`;
+    const moduleStr = entry.module ? `${ANSI.gray}[${entry.module}]${ANSI.reset} ` : '';
+    const messageStr = entry.message;
+
+    let output = `${timeStr} ${levelStr} ${moduleStr}${messageStr}`;
+
+    // Format context key=value pairs
+    if (entry.context && Object.keys(entry.context).length > 0) {
+      for (const [key, val] of Object.entries(entry.context)) {
+        output += `\n  ${ANSI.dim}${key}=${ANSI.reset}${formatContextValue(val)}`;
+      }
+    }
+
+    // Format any extra top-level structured attributes
+    const standardKeys = new Set(['level', 'message', 'timestamp', 'module', 'context', 'error']);
+    for (const [key, val] of Object.entries(entry)) {
+      if (!standardKeys.has(key)) {
+        output += `\n  ${ANSI.dim}${key}=${ANSI.reset}${formatContextValue(val)}`;
+      }
+    }
+
+    // Format error stack if present
+    if (entry.error) {
+      const errorContent = entry.error.stack || `${entry.error.name}: ${entry.error.message}`;
+      output += `\n${ANSI.red}${errorContent}${ANSI.reset}`;
+    }
+
+    return output;
+  } catch (err) {
+    // Fail-safe plain string output
+    return `${entry.timestamp} ${entry.level.toUpperCase()} ${entry.message}`;
+  }
+}

package/src/lib/logger/index.ts

@@ -0,0 +1,184 @@
+import { Logger, LoggerOptions, LogEntry, LogLevel } from './types';
+import { jsonFormatter, prettyFormatter } from './formatters';
+
+export * from './types';
+export { jsonFormatter, prettyFormatter } from './formatters';
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4,
+};
+
+/**
+ * Safely parses and normalizes log level string.
+ */
+function parseLogLevel(levelStr?: string): LogLevel | undefined {
+  if (!levelStr) return undefined;
+  const normalized = levelStr.toLowerCase() as LogLevel;
+  return normalized in LOG_LEVELS ? normalized : undefined;
+}
+
+// Determine environment
+const isDev = process.env.NODE_ENV !== 'production';
+const configuredLevel: LogLevel =
+  parseLogLevel(process.env.LOG_LEVEL) || (isDev ? 'debug' : 'info');
+const formatter = isDev ? prettyFormatter : jsonFormatter;
+
+/**
+ * Safely serializes an unknown error into structured name, message, stack details.
+ */
+function serializeError(err: unknown): { name: string; message: string; stack?: string } | undefined {
+  if (!err) return undefined;
+
+  if (err instanceof Error) {
+    return {
+      name: err.name || 'Error',
+      message: err.message,
+      stack: err.stack,
+    };
+  }
+
+  if (typeof err === 'object') {
+    const errorObj = err as Record<string, unknown>;
+    return {
+      name: typeof errorObj.name === 'string' ? errorObj.name : 'UnknownError',
+      message: typeof errorObj.message === 'string' ? errorObj.message : String(err),
+      stack: typeof errorObj.stack === 'string' ? errorObj.stack : undefined,
+    };
+  }
+
+  return {
+    name: 'Error',
+    message: String(err),
+  };
+}
+
+/**
+ * Factory function creating a structured logger instance.
+ *
+ * @param options - Configuration options including module name, base context, and min log level.
+ * @returns A structured Logger instance.
+ */
+export function createLogger(options?: LoggerOptions): Logger {
+  const minLevel: LogLevel = options?.minLevel || configuredLevel;
+  const minLevelNum = LOG_LEVELS[minLevel] ?? LOG_LEVELS.info;
+
+  const shouldLog = (level: LogLevel): boolean => {
+    const levelNum = LOG_LEVELS[level] ?? 0;
+    return levelNum >= minLevelNum;
+  };
+
+  const emit = (
+    level: LogLevel,
+    message: string,
+    err?: unknown,
+    data?: Record<string, unknown>
+  ): void => {
+    try {
+      if (!shouldLog(level)) return;
+
+      let parsedError: unknown = err;
+      let extraData = data;
+
+      // Detect if caller supplied a plain data object as the error argument
+      if (
+        err !== undefined &&
+        data === undefined &&
+        typeof err === 'object' &&
+        err !== null &&
+        !(err instanceof Error) &&
+        !('name' in err || 'message' in err || 'stack' in err)
+      ) {
+        extraData = err as Record<string, unknown>;
+        parsedError = undefined;
+      }
+
+      const mergedContext =
+        options?.context || extraData
+          ? { ...options?.context, ...extraData }
+          : undefined;
+
+      const entry: LogEntry = {
+        level,
+        message,
+        timestamp: new Date().toISOString(),
+        module: options?.module,
+        context: mergedContext,
+        error: serializeError(parsedError),
+      };
+
+      const formatted = formatter(entry);
+
+      switch (level) {
+        case 'debug':
+        case 'info':
+          console.log(formatted);
+          break;
+        case 'warn':
+          console.warn(formatted);
+          break;
+        case 'error':
+        case 'fatal':
+          console.error(formatted);
+          break;
+      }
+    } catch {
+      // Logger must never throw errors under any circumstances
+      try {
+        console.error(`[LOGGER FALLBACK] [${level.toUpperCase()}] ${message}`);
+      } catch {
+        // Silently swallow in ultimate fallback
+      }
+    }
+  };
+
+  return {
+    debug(message: string, data?: Record<string, unknown>): void {
+      emit('debug', message, undefined, data);
+    },
+    info(message: string, data?: Record<string, unknown>): void {
+      emit('info', message, undefined, data);
+    },
+    warn(message: string, data?: Record<string, unknown>): void {
+      emit('warn', message, undefined, data);
+    },
+    error(message: string, error?: unknown, data?: Record<string, unknown>): void {
+      emit('error', message, error, data);
+    },
+    fatal(message: string, error?: unknown, data?: Record<string, unknown>): void {
+      emit('fatal', message, error, data);
+    },
+    child(childOptions: { module?: string; context?: Record<string, unknown> }): Logger {
+      return createLogger({
+        module: childOptions.module
+          ? options?.module
+            ? `${options.module}:${childOptions.module}`
+            : childOptions.module
+          : options?.module,
+        context: {
+          ...options?.context,
+          ...childOptions.context,
+        },
+        minLevel: options?.minLevel,
+      });
+    },
+  };
+}
+
+/**
+ * Root logger instance pre-configured for the application.
+ */
+export const logger = createLogger({ module: 'app' });
+
+/**
+ * Convenience function to create a logger instance for a specific module and context.
+ *
+ * @param module - Module identifier (e.g., 'auth', 'database', 'billing')
+ * @param context - Optional default contextual data
+ */
+export function getLogger(module: string, context?: Record<string, unknown>): Logger {
+  return createLogger({ module, context });
+}

package/src/lib/logger/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Structured Logger Types
+ * Zero-dependency, production-grade logging types for BEMMS application.
+ */
+
+/**
+ * Log severity levels in increasing order of severity.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+/**
+ * Structured log entry representation.
+ */
+export interface LogEntry {
+  level: LogLevel;
+  message: string;
+  timestamp: string; // ISO 8601
+  module?: string;
+  context?: Record<string, unknown>;
+  error?: {
+    name: string;
+    message: string;
+    stack?: string;
+  };
+  // Additional structured data
+  [key: string]: unknown;
+}
+
+/**
+ * Configuration options for initializing or deriving a logger instance.
+ */
+export interface LoggerOptions {
+  module?: string;
+  context?: Record<string, unknown>;
+  minLevel?: LogLevel;
+}
+
+/**
+ * Structured logger interface.
+ */
+export interface Logger {
+  debug(message: string, data?: Record<string, unknown>): void;
+  info(message: string, data?: Record<string, unknown>): void;
+  warn(message: string, data?: Record<string, unknown>): void;
+  error(message: string, error?: unknown, data?: Record<string, unknown>): void;
+  fatal(message: string, error?: unknown, data?: Record<string, unknown>): void;
+  child(options: { module?: string; context?: Record<string, unknown> }): Logger;
+}

package/src/lib/notifications/create.ts

@@ -0,0 +1,71 @@
+import { db } from '@/lib/db';
+import { notifications } from '@/lib/db/schema';
+import { users } from '@/lib/db/schema';
+import { eq } from 'drizzle-orm';
+import { sendPushToUser, type PushPayload } from './push';
+
+interface CreateNotificationParams {
+  organizationId: string;
+  recipientUserId: string;
+  notificationType: 'ticket_assigned' | 'ticket_updated' | 'ticket_comment' |
+    'pm_due_soon' | 'pm_overdue' | 'calibration_due' |
+    'task_review_required' | 'task_approved' | 'task_rejected' |
+    'device_status_changed' | 'sla_warning' | 'system_alert';
+  title: string;
+  body: string;
+  relatedEntityType?: string;
+  relatedEntityId?: string;
+  actionUrl?: string;
+}
+
+// Map notification types to preference categories
+function getCategory(type: string): 'tickets' | 'maintenance' | 'devices' | 'system' {
+  if (type.startsWith('ticket_')) return 'tickets';
+  if (type.startsWith('pm_') || type.startsWith('task_') || type.startsWith('calibration_')) return 'maintenance';
+  if (type.startsWith('device_')) return 'devices';
+  return 'system';
+}
+
+export async function createNotification(params: CreateNotificationParams) {
+  // Insert notification into DB
+  const [notification] = await db.insert(notifications).values({
+    organizationId: params.organizationId,
+    recipientUserId: params.recipientUserId,
+    notificationType: params.notificationType,
+    title: params.title,
+    body: params.body,
+    relatedEntityType: params.relatedEntityType,
+    relatedEntityId: params.relatedEntityId,
+    actionUrl: params.actionUrl,
+  }).returning();
+
+  // Check user's notification preferences for push
+  const user = await db.query.users.findFirst({
+    where: eq(users.id, params.recipientUserId),
+    columns: { notificationPreferences: true },
+  });
+
+  const prefs = user?.notificationPreferences;
+  const category = getCategory(params.notificationType);
+
+  // Send push if enabled
+  const pushEnabled = prefs?.pushEnabled !== false; // Default to true
+  const categoryEnabled = prefs?.categories?.[category] !== false; // Default to true
+
+  if (pushEnabled && categoryEnabled) {
+    const payload: PushPayload = {
+      title: params.title,
+      body: params.body,
+      url: params.actionUrl || '/notifications',
+      tag: `${params.notificationType}-${params.relatedEntityId || notification.id}`,
+    };
+
+    // Fire and forget — don't block on push delivery
+    sendPushToUser(params.recipientUserId, payload).catch((err) => {
+      console.error('[Notification] Push delivery failed:', err);
+    });
+  }
+
+  return notification;
+}
+