chargeback-guard 2.0.0

package/src/core/eventEmitter.ts

@@ -0,0 +1,118 @@
+// ============================================================
+//  CHARGEBACK GUARD — Enhanced Event Emitter
+// ============================================================
+
+import { EventEmitter as NodeEventEmitter } from 'events';
+import { NotificationEvent } from '../types';
+import { createLogger } from '../utils/logger';
+
+const log = createLogger('EventEmitter');
+
+export interface EventPayload {
+  event: string;
+  timestamp: string;
+  data: Record<string, unknown>;
+}
+
+export type EventHandler = (payload: EventPayload) => void | Promise<void>;
+
+// ────────────────────────────────────────────────────────────
+//  ENHANCED EVENT EMITTER
+// ────────────────────────────────────────────────────────────
+
+export class ChargebackEventEmitter extends NodeEventEmitter {
+  private readonly eventHistory: EventPayload[] = [];
+  private readonly maxHistorySize: number = 500;
+  private readonly asyncHandlers: Map<string, EventHandler[]> = new Map();
+
+  constructor() {
+    super();
+    this.setMaxListeners(50);
+  }
+
+  // ──────────────────────────────────────────
+  //  EMIT WITH STRUCTURED PAYLOAD
+  // ──────────────────────────────────────────
+
+  emitEvent(event: NotificationEvent | string, data: Record<string, unknown>): boolean {
+    const payload: EventPayload = {
+      event,
+      timestamp: new Date().toISOString(),
+      data,
+    };
+
+    // Store in history
+    this.eventHistory.push(payload);
+    if (this.eventHistory.length > this.maxHistorySize) {
+      this.eventHistory.shift();
+    }
+
+    log.debug(`Event emitted: ${event}`, { data });
+
+    // Run async handlers
+    const asyncList = this.asyncHandlers.get(event) ?? [];
+    asyncList.forEach(handler => {
+      handler(payload).catch(err => {
+        log.error(`Async handler error for event "${event}"`, { error: err.message });
+      });
+    });
+
+    return this.emit(event, payload);
+  }
+
+  // ──────────────────────────────────────────
+  //  REGISTER ASYNC HANDLER
+  // ──────────────────────────────────────────
+
+  onAsync(event: string, handler: EventHandler): this {
+    if (!this.asyncHandlers.has(event)) {
+      this.asyncHandlers.set(event, []);
+    }
+    this.asyncHandlers.get(event)!.push(handler);
+    return this;
+  }
+
+  // ──────────────────────────────────────────
+  //  WAIT FOR EVENT (Promise-based)
+  // ──────────────────────────────────────────
+
+  waitFor(event: string, timeoutMs = 30000): Promise<EventPayload> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`Timeout waiting for event: ${event}`));
+      }, timeoutMs);
+
+      this.once(event, (payload: EventPayload) => {
+        clearTimeout(timer);
+        resolve(payload);
+      });
+    });
+  }
+
+  // ──────────────────────────────────────────
+  //  EVENT HISTORY
+  // ──────────────────────────────────────────
+
+  getHistory(event?: string): EventPayload[] {
+    if (event) {
+      return this.eventHistory.filter(e => e.event === event);
+    }
+    return [...this.eventHistory];
+  }
+
+  clearHistory(): void {
+    this.eventHistory.length = 0;
+  }
+
+  // ──────────────────────────────────────────
+  //  STATS
+  // ──────────────────────────────────────────
+
+  getStats(): Record<string, number> {
+    const stats: Record<string, number> = {};
+    this.eventHistory.forEach(({ event }) => {
+      stats[event] = (stats[event] ?? 0) + 1;
+    });
+    return stats;
+  }
+}

package/src/core/lifecycle.ts

@@ -0,0 +1,215 @@
+// ============================================================
+//  CHARGEBACK GUARD — Lifecycle Manager
+//  Handles initialization, health-checks, and graceful shutdown
+// ============================================================
+
+import { createLogger } from '../utils/logger';
+
+const log = createLogger('Lifecycle');
+
+export type LifecycleStatus =
+  | 'uninitialized'
+  | 'initializing'
+  | 'ready'
+  | 'degraded'
+  | 'shutting_down'
+  | 'terminated';
+
+export interface HealthCheck {
+  name: string;
+  status: 'healthy' | 'unhealthy' | 'degraded';
+  latencyMs?: number;
+  message?: string;
+  checkedAt: string;
+}
+
+export interface LifecycleHook {
+  name: string;
+  fn: () => Promise<void>;
+  timeout?: number;
+}
+
+// ────────────────────────────────────────────────────────────
+//  LIFECYCLE MANAGER CLASS
+// ────────────────────────────────────────────────────────────
+
+export class LifecycleManager {
+  private status: LifecycleStatus = 'uninitialized';
+  private startTime: Date = new Date();
+  private initHooks: LifecycleHook[] = [];
+  private shutdownHooks: LifecycleHook[] = [];
+  private healthCheckers: Map<string, () => Promise<HealthCheck>> = new Map();
+  private lastHealthCheck: HealthCheck[] = [];
+
+  // ──────────────────────────────────────────
+  //  STATUS MANAGEMENT
+  // ──────────────────────────────────────────
+
+  getStatus(): LifecycleStatus {
+    return this.status;
+  }
+
+  isReady(): boolean {
+    return this.status === 'ready';
+  }
+
+  getUptime(): number {
+    return Date.now() - this.startTime.getTime();
+  }
+
+  // ──────────────────────────────────────────
+  //  HOOK REGISTRATION
+  // ──────────────────────────────────────────
+
+  registerInitHook(hook: LifecycleHook): void {
+    this.initHooks.push(hook);
+    log.debug(`Init hook registered: ${hook.name}`);
+  }
+
+  registerShutdownHook(hook: LifecycleHook): void {
+    this.shutdownHooks.push(hook);
+    log.debug(`Shutdown hook registered: ${hook.name}`);
+  }
+
+  registerHealthChecker(name: string, checker: () => Promise<HealthCheck>): void {
+    this.healthCheckers.set(name, checker);
+    log.debug(`Health checker registered: ${name}`);
+  }
+
+  // ──────────────────────────────────────────
+  //  INITIALIZATION
+  // ──────────────────────────────────────────
+
+  async initialize(): Promise<void> {
+    if (this.status !== 'uninitialized') {
+      throw new Error(`Cannot initialize: current status is "${this.status}"`);
+    }
+
+    this.status = 'initializing';
+    this.startTime = new Date();
+    log.info('ChargebackGuard initializing...');
+
+    for (const hook of this.initHooks) {
+      try {
+        log.debug(`Running init hook: ${hook.name}`);
+        await this.runWithTimeout(hook.fn, hook.timeout ?? 30000, hook.name);
+        log.debug(`Init hook completed: ${hook.name}`);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`Init hook failed: ${hook.name} — ${msg}`);
+        this.status = 'degraded';
+        throw new Error(`Initialization failed at hook "${hook.name}": ${msg}`);
+      }
+    }
+
+    this.status = 'ready';
+    log.info('ChargebackGuard ready ✅', { uptimeMs: this.getUptime() });
+  }
+
+  // ──────────────────────────────────────────
+  //  GRACEFUL SHUTDOWN
+  // ──────────────────────────────────────────
+
+  async shutdown(reason = 'manual'): Promise<void> {
+    if (this.status === 'shutting_down' || this.status === 'terminated') {
+      return;
+    }
+
+    this.status = 'shutting_down';
+    log.info(`ChargebackGuard shutting down. Reason: ${reason}`);
+
+    // Run shutdown hooks in reverse order
+    for (const hook of [...this.shutdownHooks].reverse()) {
+      try {
+        log.debug(`Running shutdown hook: ${hook.name}`);
+        await this.runWithTimeout(hook.fn, hook.timeout ?? 10000, hook.name);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.warn(`Shutdown hook failed (non-fatal): ${hook.name} — ${msg}`);
+      }
+    }
+
+    this.status = 'terminated';
+    log.info('ChargebackGuard terminated.');
+  }
+
+  // ──────────────────────────────────────────
+  //  HEALTH CHECKS
+  // ──────────────────────────────────────────
+
+  async runHealthChecks(): Promise<HealthCheck[]> {
+    const results: HealthCheck[] = [];
+
+    for (const [name, checker] of this.healthCheckers.entries()) {
+      try {
+        const start = Date.now();
+        const result = await this.runWithTimeout(
+          () => checker(),
+          5000,
+          `health:${name}`
+        );
+        results.push({ ...result, latencyMs: Date.now() - start });
+      } catch (err) {
+        results.push({
+          name,
+          status: 'unhealthy',
+          message: err instanceof Error ? err.message : 'Unknown error',
+          checkedAt: new Date().toISOString(),
+        });
+      }
+    }
+
+    this.lastHealthCheck = results;
+    return results;
+  }
+
+  getLastHealthCheck(): HealthCheck[] {
+    return this.lastHealthCheck;
+  }
+
+  async getSystemHealth(): Promise<{
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    checks: HealthCheck[];
+    uptime: number;
+    lifecycleStatus: LifecycleStatus;
+  }> {
+    const checks = await this.runHealthChecks();
+    const hasUnhealthy = checks.some(c => c.status === 'unhealthy');
+    const hasDegraded = checks.some(c => c.status === 'degraded');
+
+    const overallStatus = hasUnhealthy ? 'unhealthy' : hasDegraded ? 'degraded' : 'healthy';
+
+    return {
+      status: overallStatus,
+      checks,
+      uptime: this.getUptime(),
+      lifecycleStatus: this.status,
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  PRIVATE HELPERS
+  // ──────────────────────────────────────────
+
+  private async runWithTimeout<T>(
+    fn: () => Promise<T>,
+    timeoutMs: number,
+    label: string
+  ): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`Timeout after ${timeoutMs}ms: ${label}`));
+      }, timeoutMs);
+
+      fn()
+        .then(result => {
+          clearTimeout(timer);
+          resolve(result);
+        })
+        .catch(err => {
+          clearTimeout(timer);
+          reject(err);
+        });
+    });
+  }
+}