baileys-antiban 3.8.4 → 3.8.5

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.5] - 2026-05-09
+
+### Added
+- **Observability module** (`src/observability.ts`) — Prometheus metrics export and pluggable structured logging.
+  - `exportPrometheusMetrics(stats, labels?)` — exports 27 metrics (3 counters, 24 gauges) in Prometheus text exposition format v0.0.4. Covers health score/risk, warmup progress, rate limiter windows, known chats, reply ratio, contact graph, retry spirals, reconnect throttle. Accepts custom labels (`instance`, `region`, etc.).
+  - `createMetricsHandler(getStats, labels?)` — returns Express/Fastify-compatible `handle(req, res)` + `text()` helpers for a `/metrics` endpoint.
+  - `createPeriodicExporter(getStats, config)` — push-based exporter that calls `onMetrics(text)` on a configurable interval (default 30s). Returns `stop()` handle.
+  - `createConsoleLogger(prefix?)` — structured console logger compatible with winston/pino interface (`debug`, `info`, `warn`, `error` with ISO timestamps and JSON meta).
+  - `AntiBanLogger` interface — plug in any logger: `winston`, `pino`, or the built-in console logger.
+- New exports: `createConsoleLogger`, `exportPrometheusMetrics`, `createMetricsHandler`, `createPeriodicExporter`, `AntiBanLogger`, `PeriodicExporterConfig`, `PeriodicExporterHandle`.
+
 ## [3.8.4] - 2026-05-09
 
 ### Added

package/dist/index.d.ts

@@ -38,3 +38,4 @@ export { readReceiptVariance, type ReadReceiptVariance, type ReadReceiptVariance
 export { proxyRotator, type ProxyEndpoint, type ProxyRotatorConfig, type ProxyRotatorStats, type ProxyRotatorHandle, } from './proxyRotator.js';
 export { generateSessionFingerprint, applySessionFingerprint, getMessageSendJitter, getTypingJitter, getRetryJitter, getVoiceNoteMetadata, getBatteryState, createStealthFingerprint, type SessionFingerprint, type SessionFingerprintConfig, } from './sessionFingerprint.js';
 export { getStealthSocketConfig, rampPresenceAfterConnect, STEALTH_BROWSER_POOL, AbortError, type BrowserTuple, type StealthSocketConfig, type GetStealthSocketConfigOptions, type RampPresenceOptions, type PresenceCapableSocket, } from './stealthConnect.js';
+export { createConsoleLogger, exportPrometheusMetrics, createMetricsHandler, createPeriodicExporter, type AntiBanLogger, type PeriodicExporterConfig, type PeriodicExporterHandle, } from './observability.js';

package/dist/index.js

@@ -53,3 +53,5 @@ export { proxyRotator, } from './proxyRotator.js';
 export { generateSessionFingerprint, applySessionFingerprint, getMessageSendJitter, getTypingJitter, getRetryJitter, getVoiceNoteMetadata, getBatteryState, createStealthFingerprint, } from './sessionFingerprint.js';
 // v3.8 new modules
 export { getStealthSocketConfig, rampPresenceAfterConnect, STEALTH_BROWSER_POOL, AbortError, } from './stealthConnect.js';
+// Observability
+export { createConsoleLogger, exportPrometheusMetrics, createMetricsHandler, createPeriodicExporter, } from './observability.js';

package/dist/observability.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Observability — Prometheus metrics export + pluggable structured logging
+ *
+ * Usage:
+ *   // Logging
+ *   import { createConsoleLogger } from 'baileys-antiban';
+ *   const logger = createConsoleLogger('[my-bot]');
+ *   logger.info('Message sent', { recipient: jid });
+ *
+ *   // Metrics export for Express
+ *   import { createMetricsHandler } from 'baileys-antiban';
+ *   const metricsHandler = createMetricsHandler(() => antiban.getStats());
+ *   app.get('/metrics', metricsHandler.handle);
+ *
+ *   // Periodic push to external system
+ *   import { createPeriodicExporter } from 'baileys-antiban';
+ *   const exporter = createPeriodicExporter(() => antiban.getStats(), {
+ *     intervalMs: 30_000,
+ *     onMetrics: (text) => pushToVictoriaMetrics(text),
+ *   });
+ */
+import type { AntiBanStats } from './antiban.js';
+/**
+ * Pluggable logger interface compatible with winston, pino, console
+ */
+export interface AntiBanLogger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Create a simple console logger with timestamps and prefix
+ */
+export declare function createConsoleLogger(prefix?: string): AntiBanLogger;
+/**
+ * Export AntiBan stats as Prometheus text format (exposition format v0.0.4)
+ */
+export declare function exportPrometheusMetrics(stats: AntiBanStats, labels?: Record<string, string>): string;
+/**
+ * Create an HTTP handler for Prometheus metrics (Express/Fastify compatible)
+ */
+export declare function createMetricsHandler(getStats: () => AntiBanStats, labels?: Record<string, string>): {
+    /**
+     * HTTP request handler (Express/Fastify compatible)
+     */
+    handle: (_req: unknown, res: {
+        setHeader: (name: string, value: string) => void;
+        end: (data: string) => void;
+    }) => void;
+    /**
+     * Get metrics as plain text (for non-HTTP usage)
+     */
+    text: () => string;
+};
+/**
+ * Configuration for periodic metrics export
+ */
+export interface PeriodicExporterConfig {
+    /**
+     * Export interval in milliseconds (default: 30000)
+     */
+    intervalMs?: number;
+    /**
+     * Callback invoked with Prometheus text on each interval
+     */
+    onMetrics: (text: string) => void;
+    /**
+     * Additional labels to attach to all metrics
+     */
+    labels?: Record<string, string>;
+}
+/**
+ * Handle for controlling periodic export
+ */
+export interface PeriodicExporterHandle {
+    /**
+     * Stop the periodic exporter
+     */
+    stop(): void;
+}
+/**
+ * Create a periodic metrics exporter that calls onMetrics on an interval
+ */
+export declare function createPeriodicExporter(getStats: () => AntiBanStats, config: PeriodicExporterConfig): PeriodicExporterHandle;

package/dist/observability.js

@@ -0,0 +1,145 @@
+/**
+ * Observability — Prometheus metrics export + pluggable structured logging
+ *
+ * Usage:
+ *   // Logging
+ *   import { createConsoleLogger } from 'baileys-antiban';
+ *   const logger = createConsoleLogger('[my-bot]');
+ *   logger.info('Message sent', { recipient: jid });
+ *
+ *   // Metrics export for Express
+ *   import { createMetricsHandler } from 'baileys-antiban';
+ *   const metricsHandler = createMetricsHandler(() => antiban.getStats());
+ *   app.get('/metrics', metricsHandler.handle);
+ *
+ *   // Periodic push to external system
+ *   import { createPeriodicExporter } from 'baileys-antiban';
+ *   const exporter = createPeriodicExporter(() => antiban.getStats(), {
+ *     intervalMs: 30_000,
+ *     onMetrics: (text) => pushToVictoriaMetrics(text),
+ *   });
+ */
+/**
+ * Create a simple console logger with timestamps and prefix
+ */
+export function createConsoleLogger(prefix = '[baileys-antiban]') {
+    const format = (level, msg, meta) => {
+        const timestamp = new Date().toISOString();
+        const metaStr = meta ? ' ' + JSON.stringify(meta) : '';
+        return `${timestamp} ${level} ${prefix} ${msg}${metaStr}`;
+    };
+    return {
+        debug: (msg, meta) => console.log(format('DEBUG', msg, meta)),
+        info: (msg, meta) => console.log(format('INFO', msg, meta)),
+        warn: (msg, meta) => console.warn(format('WARN', msg, meta)),
+        error: (msg, meta) => console.error(format('ERROR', msg, meta)),
+    };
+}
+/**
+ * Export AntiBan stats as Prometheus text format (exposition format v0.0.4)
+ */
+export function exportPrometheusMetrics(stats, labels) {
+    const labelMap = { instance: 'default', ...labels };
+    const labelStr = Object.entries(labelMap)
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(',');
+    const lines = [];
+    const addMetric = (name, type, help, value) => {
+        lines.push(`# HELP ${name} ${help}`);
+        lines.push(`# TYPE ${name} ${type}`);
+        lines.push(`${name}{${labelStr}} ${value}`);
+    };
+    // Counters
+    addMetric('antiban_messages_allowed_total', 'counter', 'Total messages allowed by AntiBan', stats.messagesAllowed);
+    addMetric('antiban_messages_blocked_total', 'counter', 'Total messages blocked by AntiBan', stats.messagesBlocked);
+    addMetric('antiban_total_delay_ms_total', 'counter', 'Total delay imposed (milliseconds)', stats.totalDelayMs);
+    // Health gauges
+    const riskMap = { low: 0, medium: 1, high: 2, critical: 3 };
+    addMetric('antiban_health_score', 'gauge', 'Current health score (0=best, 100=worst)', stats.health.score);
+    addMetric('antiban_health_risk', 'gauge', 'Risk level encoded as number (0=low, 1=medium, 2=high, 3=critical)', riskMap[stats.health.risk] ?? 0);
+    addMetric('antiban_disconnects_last_hour', 'gauge', 'Disconnects in last hour', stats.health.stats.disconnectsLastHour);
+    addMetric('antiban_failed_messages_last_hour', 'gauge', 'Failed messages in last hour', stats.health.stats.failedMessagesLastHour);
+    addMetric('antiban_uptime_ms', 'gauge', 'Session uptime in milliseconds', stats.health.stats.uptimeMs);
+    // Warm-up gauges
+    addMetric('antiban_warmup_progress', 'gauge', 'Warm-up progress (0.0 to 1.0)', stats.warmUp.progress);
+    addMetric('antiban_warmup_day', 'gauge', 'Current warm-up day', stats.warmUp.day);
+    addMetric('antiban_warmup_today_sent', 'gauge', 'Messages sent today during warm-up', stats.warmUp.todaySent);
+    addMetric('antiban_warmup_today_limit', 'gauge', 'Message limit for today during warm-up', stats.warmUp.todayLimit);
+    // Rate limiter gauges
+    addMetric('antiban_rate_last_minute', 'gauge', 'Messages sent in last minute', stats.rateLimiter.lastMinute);
+    addMetric('antiban_rate_last_hour', 'gauge', 'Messages sent in last hour', stats.rateLimiter.lastHour);
+    addMetric('antiban_rate_last_day', 'gauge', 'Messages sent in last day', stats.rateLimiter.lastDay);
+    addMetric('antiban_rate_limit_per_minute', 'gauge', 'Rate limit per minute', stats.rateLimiter.limits.perMinute);
+    addMetric('antiban_rate_limit_per_hour', 'gauge', 'Rate limit per hour', stats.rateLimiter.limits.perHour);
+    addMetric('antiban_rate_limit_per_day', 'gauge', 'Rate limit per day', stats.rateLimiter.limits.perDay);
+    addMetric('antiban_known_chats', 'gauge', 'Number of known chats', stats.rateLimiter.knownChats);
+    // Reply ratio gauges (optional)
+    if (stats.replyRatio) {
+        addMetric('antiban_contacts_on_cooldown', 'gauge', 'Contacts currently on reply cooldown', stats.replyRatio.contactsOnCooldown);
+    }
+    else {
+        addMetric('antiban_contacts_on_cooldown', 'gauge', 'Contacts currently on reply cooldown', 0);
+    }
+    // Contact graph gauges (optional)
+    if (stats.contactGraph) {
+        addMetric('antiban_known_contacts', 'gauge', 'Number of known contacts', stats.contactGraph.knownContacts);
+        addMetric('antiban_pending_handshakes', 'gauge', 'Pending handshakes', stats.contactGraph.pendingHandshakes);
+    }
+    else {
+        addMetric('antiban_known_contacts', 'gauge', 'Number of known contacts', 0);
+        addMetric('antiban_pending_handshakes', 'gauge', 'Pending handshakes', 0);
+    }
+    // Retry tracker gauges (optional)
+    if (stats.retryTracker) {
+        addMetric('antiban_retry_spirals', 'gauge', 'Number of retry spirals detected', stats.retryTracker.spiralsDetected);
+        addMetric('antiban_active_retries', 'gauge', 'Currently active retries', stats.retryTracker.activeRetries);
+    }
+    else {
+        addMetric('antiban_retry_spirals', 'gauge', 'Number of retry spirals detected', 0);
+        addMetric('antiban_active_retries', 'gauge', 'Currently active retries', 0);
+    }
+    // Reconnect throttle gauges (optional)
+    if (stats.reconnectThrottle) {
+        addMetric('antiban_reconnect_throttled', 'gauge', 'Whether reconnect is currently throttled (0=no, 1=yes)', stats.reconnectThrottle.isThrottled ? 1 : 0);
+        addMetric('antiban_lifetime_reconnects', 'gauge', 'Total reconnects in session lifetime', stats.reconnectThrottle.lifetimeReconnects);
+    }
+    else {
+        addMetric('antiban_reconnect_throttled', 'gauge', 'Whether reconnect is currently throttled (0=no, 1=yes)', 0);
+        addMetric('antiban_lifetime_reconnects', 'gauge', 'Total reconnects in session lifetime', 0);
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Create an HTTP handler for Prometheus metrics (Express/Fastify compatible)
+ */
+export function createMetricsHandler(getStats, labels) {
+    return {
+        /**
+         * HTTP request handler (Express/Fastify compatible)
+         */
+        handle: (_req, res) => {
+            const metrics = exportPrometheusMetrics(getStats(), labels);
+            res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+            res.end(metrics);
+        },
+        /**
+         * Get metrics as plain text (for non-HTTP usage)
+         */
+        text: () => {
+            return exportPrometheusMetrics(getStats(), labels);
+        },
+    };
+}
+/**
+ * Create a periodic metrics exporter that calls onMetrics on an interval
+ */
+export function createPeriodicExporter(getStats, config) {
+    const intervalMs = config.intervalMs ?? 30_000;
+    const intervalId = setInterval(() => {
+        const metrics = exportPrometheusMetrics(getStats(), config.labels);
+        config.onMetrics(metrics);
+    }, intervalMs);
+    return {
+        stop: () => clearInterval(intervalId),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baileys-antiban",
-  "version": "3.8.4",
+  "version": "3.8.5",
   "description": "Anti-ban middleware for Baileys WhatsApp bots. Rate limiting, warmup, health monitor, LID resolver, disconnect classifier. Free Whapi.Cloud alternative.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",