Added recordConnectionError() function and integrated it into socket.ts
to track connection errors by type:
- connection_closed
- connection_lost
- connection_replaced
- timed_out
- logged_out
- bad_session
- restart_required
- multidevice_mismatch
- error_{code} for other status codes
The metric was defined but never incremented when buffer overflow occurred.
Added recordBufferOverflow() function and call it from checkBufferOverflow()
when buffer exceeds maxBufferSize (default 5000 events).
The metric was defined but never incremented when LRU cleanup happened.
Added recordCacheCleanup() function and call it from cleanupHistoryCache()
when cache entries are removed due to exceeding maxHistoryCacheSize.
The buffer_cache_size metric was defined but never updated, always showing 0.
Fix:
- Add historyCacheSize parameter to recordBufferFlush function
- Pass historyCache.size from event-buffer.ts when recording flush metrics
- Update both bufferCacheSize and bufferHistoryCacheSize metrics
The buffer_flushes_total metric was registered twice with different labels:
- In main metrics object: ['type', 'reason']
- In getEventBufferMetrics(): ['forced']
This caused recordBufferFlush() to silently fail because it tried to
increment with { forced } labels but the registered metric expected
{ type, reason } labels.
Fix:
- Remove duplicate bufferFlushes from getEventBufferMetrics()
- Update recordBufferFlush() to use metrics.bufferFlushes with correct labels
- Update recordEventBuffered() to use main metrics.eventsBuffered
- Rename local variable to avoid shadowing global metrics object
Previously, buffer metrics required a separate BAILEYS_BUFFER_METRICS=true
env variable even when BAILEYS_PROMETHEUS_ENABLED=true was set. This caused
the buffer_flushes_total metric to have no data even though flushes were
occurring.
Now buffer metrics are enabled automatically when either BAILEYS_BUFFER_METRICS
or BAILEYS_PROMETHEUS_ENABLED is set to true.
Added new metrics:
- active_connections: Number of active WhatsApp connections
- connection_errors_total: Total connection errors by type
- buffer_destroyed_total: Total buffers destroyed
- buffer_final_flush_total: Final flushes during destruction
- buffer_cache_cleanup_total: Cache cleanup operations
- buffer_cache_size: Current buffer cache size
- adaptive_health_status: System health (0=unhealthy, 1=healthy)
- adaptive_event_rate: Current event rate per second
These metrics are required for the Grafana dashboard to display all panels correctly.
Check if nodejs_eventloop_lag_seconds metric already exists before creating
it in SystemMetricsCollector. This prevents conflicts when collectDefaultMetrics
from prom-client has already registered metrics with the same name.
Added helper functions metricExists() and getExistingMetric() to safely
check and retrieve existing metrics from the custom registry.
The Prometheus metrics server was implemented but never started because
initializeMetrics() was never called. This fix adds automatic initialization
when the module is loaded and BAILEYS_PROMETHEUS_ENABLED=true.
This ensures the /metrics endpoint is available without requiring manual
initialization in the application code.
When hkdf became async, mutationKeys also became async but the call
site wasn't updated. This caused Promise<Promise<Key>> instead of
Promise<Key>, breaking contact sync events (contacts.upsert).
Ref: WhiskeySockets/Baileys#2288
- Replace Function type with proper VersionCacheLogger interface
- Add documentation for cacheFilePath about container/serverless limitations
- Handle fetchInProgress in clearVersionCache to prevent cache restoration
- Add deduplication check in refreshVersionCache
- Remove unused fetchLatestWaWebVersion import
- Return success status from refreshVersionCache to detect fallback
- Fix inefficient getCachedVersion call - use cacheStatus.version directly
- Remove as any casts by using logger adapter pattern
- Don't downgrade version on transient network errors
Fixes from code review:
1. Fix #1,6: Use connection.update event instead of overriding sock.end()
- Listens for 'close' event to cleanup interval
- Handles both explicit close and internal disconnections
2. Fix#3: Exit code 2 when fetch fails (not 0)
- Allows CI to distinguish success/error/fetch-failed
- Properly signals fetch failures to workflows
3. Fix#4: Document revision bounds + add env vars
- Added detailed comments explaining min/max revision values
- Made configurable via WA_MIN_REVISION/WA_MAX_REVISION env vars
4. Fix #5,9: Remove unused fetchLatestVersion option
- Removed from SocketConfig and defaults
- Updated versionCheckIntervalMs docs to clarify it's only for makeWASocketAutoVersion
5. Fix#7: Use separate variable for version tracking
- trackedVersion instead of mutating mergedConfig
- Prevents unexpected side effects
6. Fix#8: Check socket state before emitting events
- isSocketClosed flag to prevent race conditions
- Double-check after async operations
7. Fix#10: Implement force parameter in workflow
- Creates PR even without version changes when force=true
- Useful for re-triggering updates manually
Note: Test coverage (Fix#2) deferred to separate PR due to
ESM mocking complexity with Jest.
Implements automatic version updates that are transparent to users:
- Checks for new WhatsApp Web version every 6 hours (configurable)
- When new version detected, saves it for next natural reconnection
- Emits 'version.update' event so users can track updates
- No disconnection required - WhatsApp naturally reconnects every 30min-2h
- Cleans up interval when socket closes
Configuration:
```typescript
const sock = await makeWASocketAutoVersion({
auth: state,
versionCheckIntervalMs: 6 * 60 * 60 * 1000 // 6 hours (default)
})
sock.ev.on('version.update', ({ currentVersion, newVersion, isCritical }) => {
console.log(`New version: ${newVersion.join('.')}`)
})
```
Adds a new async function that automatically fetches the latest
WhatsApp Web version from web.whatsapp.com before connecting.
Usage:
```typescript
// Option 1: Auto-fetch version (recommended)
const sock = await makeWASocketAutoVersion({ auth: state })
// Option 2: Manual version (existing behavior)
const sock = makeWASocket({ auth: state })
```
Benefits:
- No need to update library for version changes
- Automatic fallback to bundled version if fetch fails
- Logged warnings when using fallback
Instead of maintaining the version number in 3 separate files
(baileys-version.json, index.ts, generics.ts), this change makes
baileys-version.json the single source of truth. Other files now
import the version from this JSON file.
This follows the DRY principle and reduces:
- Risk of version inconsistency across files
- Maintenance burden (only 1 file to update)
- PR diff size (3 files → 1 file for version updates)
- Merge conflict probability
Addresses inefficiency found in Baileys PR #2269.
Messages from Facebook/Instagram ads (Click-to-WhatsApp) don't arrive on
linked devices because Meta's ads endpoint doesn't encrypt for multi-device.
They arrive as "Message absent from node" placeholders.
This change automatically requests the message from the primary phone via
PDO (Peer Data Operation) when a CTWA placeholder is detected.
Changes:
- Add enableCTWARecovery config option (default: true)
- Trigger requestPlaceholderResend() for "Message absent from node" errors
- Add Prometheus metrics for CTWA recovery tracking
- Add comprehensive unit tests for CTWA recovery functionality
Resolves: https://github.com/WhiskeySockets/Baileys/issues/1723
Resolves: https://github.com/WhiskeySockets/Baileys/issues/1034
Merge master branch and resolve conflicts:
- Use import from '../WABinary/index.js' (master convention)
- Keep the bug fix: || instead of && in extractLidPnFromMessage
- Combine comprehensive tests from both branches
- Use Map for deduplication (master implementation)
All 55 tests passing.
Address PR #20 code review feedback:
- Fix logical bug: changed `&&` to `||` in isPersonJid validation
This ensures BOTH JIDs must be person JIDs before extracting
a LID-PN mapping, preventing "poisoned" mappings where one side
is a group/newsletter/broadcast
- Add isPersonJid() helper to validate JID types
- Add extractLidPnFromConversation() to extract mappings from
conversation lidJid/pnJid properties
- Add extractLidPnFromMessage() to extract mappings from message
remoteJidAlt/participantAlt fields
- Update processHistoryMessage() to use new extraction functions
- Add comprehensive tests covering edge cases for mixed JID types
(person + group, person + broadcast, person + newsletter)
Note: Returning `undefined` is the correct TypeScript convention
for indicating absence of value (as per TypeScript team guidelines)
Enhances LID-PN mapping extraction to handle all WhatsApp JID formats
and extract mappings from multiple sources within history sync data.
New JID validation:
- Add `isPersonJid()` helper to identify JIDs that can have LID-PN mappings
- Skip non-person JIDs: @newsletter (channels), @broadcast, @g.us (groups)
Triple-source extraction:
1. Top-level `phoneNumberToLidMappings` array (existing)
2. Conversation objects via `lidJid`/`pnJid` properties (existing)
3. Message objects via `remoteJidAlt`/`participantAlt` fields (NEW)
New `extractLidPnFromMessage()` function:
- Extracts mappings from message key alternative JID fields
- Handles both direct messages (remoteJidAlt) and group messages (participantAlt)
- Properly identifies LID vs PN based on server type
JID formats handled:
- @s.whatsapp.net - Standard phone number
- @lid - Logical ID (privacy)
- @hosted - Hosted phone number
- @hosted.lid - Hosted LID
46 comprehensive tests covering all scenarios.
Related: WhiskeySockets/Baileys#2263
WhatsApp provides LID-PN mappings in two locations within history sync:
1. Top-level `phoneNumberToLidMappings` array (already processed)
2. Individual conversation objects with `lidJid`/`pnJid` properties (new)
This change adds extraction from conversation objects, ensuring maximum
mapping coverage regardless of sync type or payload structure.
Key improvements:
- Add `extractLidPnFromConversation()` function with comprehensive JSDoc
- Use Map for O(1) deduplication of mappings across both sources
- Handle all JID formats: @lid, @hosted.lid, @s.whatsapp.net, @hosted
- Normalize JIDs using `jidNormalizedUser()` for consistency
- Skip group chats (@g.us) that don't have LID-PN mappings
Includes 22 comprehensive tests covering:
- LID chat with pnJid extraction
- PN chat with lidJid extraction
- Hosted format handling
- Deduplication between sources
- Edge cases (nulls, groups, missing data)
- All conversation sync types
Related: WhiskeySockets/Baileys#2263
See-also: WhiskeySockets/Baileys#2282
Wrap URL parsing in try/catch to prevent server crashes from malformed
requests (invalid percent-encoding, problematic Host headers, etc.).
Returns 400 Bad Request instead of crashing the process.
Prometheus Metrics:
- Add METRICS_LABELS fallback for defaultLabels env config
- Separate includeSystem from collectDefaultMetrics with own env var
- Parse URL in /metrics endpoint to support querystrings and trailing slashes
- Sort keys in labelsToKey for stable/deterministic lookups
- Update documentation with all environment variables
Retry Utils:
- Remove abort listener on sleep completion to prevent memory leak
- Apply maxDelay cap AFTER jitter to guarantee max delay limit
- Validate/normalize attempt parameter in calculateDelay
- Count retries only when attempt > 1 (actual retry, not first try)
- Use metrics.retryExhausted instead of generic errors for exhausted retries
Tests:
- Add consistency tests to verify retryConfigs.rsocket matches constants
- Re-export RETRY_BACKOFF_DELAYS and RETRY_JITTER_FACTOR from Defaults
for backwards compatibility with existing imports
- Add 'as const' to RETRY_JITTER_FACTOR for type consistency
- Improve documentation explaining why values are hardcoded in retryConfigs
(ESM initialization order issues with indirect circular imports)
Hardcode values in retryConfigs.rsocket instead of referencing
RETRY_BACKOFF_DELAYS and RETRY_JITTER_FACTOR to avoid
"Cannot access before initialization" error in ESM module loading.
- Remove duplicate RETRY_BACKOFF_DELAYS and RETRY_JITTER_FACTOR from Defaults/index.ts
- Export constants from retry-utils.ts as single source of truth
- Add 'as const' for better type inference
- Fixes "Cannot access 'RETRY_BACKOFF_DELAYS' before initialization" error
- Add registryConfigured flag to ensure single execution of configureRegistry
- Fix race condition by moving setMetricPrefix/configureRegistry before Promise
- Remove unused prefix parameter from configureRegistry function
- Consolidate prefix to single source of truth (configuredPrefix global)
- Allow clearing default labels by passing empty object
- Add resetMetricsConfiguration() and getConfiguredPrefix() for testing
- Apply configured prefix to all metric names via getFullMetricName()
- Configure customRegistry with defaultLabels at initialization
- Prevent memory leak: collectDefaultMetrics only called once via flag
- collectDefaultMetrics now uses customRegistry instead of global
- Initialize prefix/defaultLabels before creating baileysMetrics
All metrics now properly include prefix (e.g., baileys_connection_attempts)
and inherit defaultLabels configured via environment variables.
Major improvements to prometheus-metrics.ts:
- Use custom registry instead of global promClient.register (isolation)
- Remove duplicate localValues - prom-client is now single source of truth
- Fix reset(labels) to respect labels param using remove() instead of reset()
- Migrate Summary class to use prom-client internally
- getMetricsOutput() now uses customRegistry for proper isolation
Fix misleading comments in retry-utils.ts:
- Change "exponential backoff" to "custom progressive backoff"
- Fix comment claiming constants are "from Defaults" (now local)
Breaking changes to getValues()/get() - now async as they query prom-client
Define RETRY_BACKOFF_DELAYS and RETRY_JITTER_FACTOR locally in
retry-utils.ts to avoid circular dependency that caused
"Cannot access 'RETRY_BACKOFF_DELAYS' before initialization" error.
- Add prom-client ^15.1.3 as production dependency
- Migrate Counter class to use prom-client internally
- Migrate Gauge class to use prom-client internally
- Migrate Histogram class to use prom-client internally
- Update getMetricsOutput() to use prom-client's native metrics()
- Update contentType() to use prom-client's contentType
- Enable collectDefaultMetrics() for Node.js system metrics
- Maintain backward compatibility with existing API
Benefits:
- Native OpenMetrics format export
- Proper histogram bucket handling
- Default Node.js metrics (memory, CPU, event loop, GC)
- Better integration with Grafana/Prometheus ecosystem
- Integrate RETRY_BACKOFF_DELAYS and RETRY_JITTER_FACTOR into retry-utils.ts
- Add retryConfigs.rsocket using the default delays
- Add getRetryDelayWithJitter() helper function
- Add getAllRetryDelaysWithJitter() for planning
- Document DEFAULT_CACHE_MAX_KEYS with usage example
- Adjust INITIAL_PREKEY_COUNT from 30 to 200 (moderate value)
- Adjust MIN_UPLOAD_INTERVAL from 60s to 10s (balance rate limiting/responsiveness)
- Revert syncFullHistory to true (avoid breaking change)
Based on RSocket's battle-tested configuration:
- Add maxWebSocketListeners config option (default: 20)
- 8 base WS events + 10 dynamic listeners + 2 buffer slots
- Add maxSocketClientListeners config option (default: 50)
- Replace dangerous setMaxListeners(0) with configurable limits
- Add warning log if user explicitly sets limit to 0
BREAKING: Previous behavior used setMaxListeners(0) which removed
all limits. Now defaults to safe limits but can be overridden via config.
Claude