Add extractPnFromMessages() function to extract phone numbers from
userReceipt fields when pnJid is missing in LID conversations.
This is a cherry-pick of the functionality from upstream PR #2282
(commit f829b6d7a) integrated with our existing LID-PN extraction logic.
Closes: WhiskeySockets/Baileys#2282
Metrics with labels only appear in Prometheus output after being
incremented at least once. This fix pre-initializes all labeled metrics
with zero values so they appear in Grafana dashboards immediately,
including buffer_destroyed_total which was showing "No data".
Added metrics tracking for:
- message_retries_total: Incremented when message retry is attempted
- message_failures_total: Incremented when max retries reached or encryption fails
Note: messages_queued metric is not applicable as this implementation
sends messages directly without an explicit queue system.
Added metrics tracking for:
- circuit_breaker_trips_total: Incremented when circuit opens
- adaptive_health_status: 1 if healthy (not in aggressive mode), 0 otherwise
- adaptive_event_rate: Current events per second
Added methods to AdaptiveTimeoutCalculator:
- getEventRate(): Returns current event rate in events/second
- isHealthy(): Returns true if not in aggressive mode
Metrics are updated on each buffer flush when adaptive timeout is enabled.
Added recordBufferDestroyed() and recordBufferFinalFlush() functions
and integrated into destroy() function in event-buffer.ts.
Tracks:
- Buffer destruction with reason and whether there was pending flush
- Final flushes that occur during buffer destruction
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
Changes:
- Update frequency: weekly → daily (06:00 UTC)
- Add retry with exponential backoff (3 attempts per source)
- Add multiple source endpoints (sw.js + bootstrap page)
- Add version validation (sanity checks on revision numbers)
- Add fetch timeout to prevent hanging
- Add detailed logging for debugging
- Simplify workflow to only update baileys-version.json
This makes the version update more reliable and responsive
to WhatsApp Web changes.
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 comprehensive unit tests for CTWA recovery functionality
Resolves: https://github.com/WhiskeySockets/Baileys/issues/1723
Resolves: https://github.com/WhiskeySockets/Baileys/issues/1034
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
Motivation
Avoid duplicate contacts when the same user arrives sometimes as a PN and sometimes as a LID.
Ensure that LID↔PN mappings acquired via history and event synchronization are used immediately.
Improved performance and scalability with batch searches (inspired by PR #2274).
Description
Incoming JID normalization: added normalizeMessageJids to convert remoteJid/participant LID → PN when available, keeping LID as fallback if PN does not already exist.
Batch lookups: getLIDsForPNs and getPNsForLIDs now use batch DB, bidirectional caching, and fallback to USync, reducing individual calls.
Automatic hydration: lidPnMappings from history sync are persisted in the store so that future LID messages are resolved immediately.
Fallback logs: logs detail when LID→PN resolves and when new mappings are stored (history sync and lid-mapping.update).
Tests
Added tests for batch PN→LID, batch LID→PN, and LID→PN normalization fallback.
✅ Changes applied
Summary
Added batch tests for PN→LID and LID→PN resolution
Added tests for normalizeMessageJids cobrindo sucesso e fallback (LID permanece quando PN não existe).
This folder contains the files ready for upstream WhiskeySockets/Baileys PR:
Changes to src/Utils/history.ts:
- Add isPersonJid() helper to validate JID types for mapping eligibility
- Add extractLidPnFromConversation() for conversation-level mapping extraction
- Add extractLidPnFromMessage() for message-level mapping extraction
- Modify processHistoryMessage() to extract from 3 sources with deduplication
- Fix validation bug: use || (OR) instead of && (AND) to prevent poisoned mappings
Changes to src/__tests__/Utils/history.test.ts:
- 55 comprehensive tests covering all new functions and edge cases
- Tests for all JID formats (@lid, @hosted.lid, @s.whatsapp.net, @hosted)
- Tests for skipped JIDs (@g.us, @broadcast, @newsletter)
- Tests for bug fix validation (person + group, person + broadcast, etc.)
- Tests for deduplication across all three sources
Related issues:
- ClosesWhiskeySockets/Baileys#2282
- Partially addresses WhiskeySockets/Baileys#2281
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
Claude