@neelegirl/baileys 2.1.6 → 2.1.8

package/README.md

@@ -19,7 +19,7 @@
 
 | Package | Version | Main goal |
 |---|---:|---|
-| `@neelegirl/baileys` | `2.1.6` | Stable Neelegirl fork with preserved project-specific runtime behavior |
+| `@neelegirl/baileys` | `2.1.8` | Stable Neelegirl fork with preserved project-specific runtime behavior |
 
 [Installation](#installation) · [Quickstart](#quickstart) · [Protected logic](#protected-logic) · [Device and LID notes](#device-and-lid-notes) · [Verified exports](#verified-exports) · [Release notes](#release-notes)
 
@@ -32,7 +32,7 @@
 - [Overview](#overview)
 - [Why this fork exists](#why-this-fork-exists)
 - [Protected logic](#protected-logic)
-- [What was updated in 2.1.6](#what-was-updated-in-216)
+- [What was updated in 2.1.8](#what-was-updated-in-218)
 - [Installation](#installation)
 - [Imports](#imports)
 - [Quickstart](#quickstart)
@@ -83,6 +83,21 @@ The following logic was explicitly treated as protected during maintenance:
 
 Nothing in those areas was blindly replaced with upstream code.
 
+## What was updated in 2.1.8
+
+### Runtime hotfixes
+
+- fixed `lru-cache` compatibility so the local CommonJS build works with both direct-class and named-export variants
+- unblocked `LIDMappingStore` initialization during real bot startup
+- unblocked the migrated session cache and retry caches that rely on the same constructor shape
+- kept QR flow, `NEELE` message-ID logic, and project-specific device/watch handling untouched
+
+### Verified after the hotfix
+
+- multi-session startup completed successfully in the local Neelegirl runtime
+- LID/device watch output continued to work after the patch
+- the package now starts without the `LRUCache is not a constructor` crash seen before this release
+
 ## What was updated in 2.1.6
 
 ### Runtime compatibility
@@ -517,7 +532,1114 @@ The following items were verified in the currently prepared package before publi
 - no restrictive `exports` map was added because that would risk breaking existing CommonJS consumers
 - some upstream files remain intentionally absent because the local Neelegirl fork structure differs by design
 
-## Release notes
+## Deep-dive: message handling
+
+This fork pays extra attention to message handling because several Neelegirl-specific customizations already depend on richer metadata than a plain "text or media" abstraction.
+
+### Why message handling is sensitive here
+
+The package needs to preserve behavior around:
+
+- `conversation`
+- `extendedTextMessage`
+- `imageMessage`
+- `videoMessage`
+- `documentMessage`
+- `contextInfo`
+- `participant`
+- `participantAlt`
+- `remoteJid`
+- `remoteJidAlt`
+- normalized sender values
+- device and platform labels
+
+That is why the maintenance pass intentionally avoided broad message-processing rewrites.
+
+### Reading text safely
+
+For many bots, the most robust quick read path is still:
+
+```js
+const text =
+  message?.message?.conversation ||
+  message?.message?.extendedTextMessage?.text ||
+  ''
+```
+
+This stays valid because the fork intentionally keeps compatibility with the most common text cases.
+
+### Example: normalize the sender view
+
+```js
+const {
+  jidDecode,
+  jidNormalizedUser,
+  isLidUser,
+  isPnUser
+} = require('@neelegirl/baileys')
+
+function inspectSender(msg) {
+  const raw =
+    msg?.key?.participant ||
+    msg?.participant ||
+    msg?.key?.remoteJid ||
+    ''
+
+  const normalized = jidNormalizedUser(raw)
+  const decoded = jidDecode(raw)
+
+  return {
+    raw,
+    normalized,
+    decoded,
+    isPn: isPnUser(raw),
+    isLid: isLidUser(raw)
+  }
+}
+```
+
+### Example: handle text, media, and fallback cleanly
+
+```js
+function getPrimaryContent(msg) {
+  const m = msg?.message || {}
+
+  if (m.conversation) {
+    return { type: 'conversation', text: m.conversation }
+  }
+
+  if (m.extendedTextMessage?.text) {
+    return { type: 'extendedTextMessage', text: m.extendedTextMessage.text }
+  }
+
+  if (m.imageMessage) {
+    return {
+      type: 'imageMessage',
+      caption: m.imageMessage.caption || ''
+    }
+  }
+
+  if (m.videoMessage) {
+    return {
+      type: 'videoMessage',
+      caption: m.videoMessage.caption || ''
+    }
+  }
+
+  if (m.documentMessage) {
+    return {
+      type: 'documentMessage',
+      fileName: m.documentMessage.fileName || ''
+    }
+  }
+
+  return { type: 'unknown' }
+}
+```
+
+### Conversation vs extended text
+
+The classic split is still important:
+
+| Field | Typical use |
+|---|---|
+| `conversation` | direct simple text |
+| `extendedTextMessage.text` | richer text message with more surrounding metadata |
+
+Bots that only read one of the two will still miss messages in practice.
+
+### Media notes
+
+Current helpers still support common media workflows:
+
+- send image
+- send video
+- send audio
+- send sticker
+- send document
+- download received media
+- request media re-upload when needed
+
+### Downloading media carefully
+
+```js
+const {
+  downloadMediaMessage,
+  getContentType
+} = require('@neelegirl/baileys')
+
+sock.ev.on('messages.upsert', async ({ messages }) => {
+  const msg = messages[0]
+  if (!msg?.message) {
+    return
+  }
+
+  const type = getContentType(msg.message)
+  if (type === 'imageMessage') {
+    const buffer = await downloadMediaMessage(
+      msg,
+      'buffer',
+      {},
+      {
+        logger: sock.logger,
+        reuploadRequest: sock.updateMediaMessage
+      }
+    )
+
+    console.log('downloaded image bytes:', buffer.length)
+  }
+})
+```
+
+### Polls, reactions, edits
+
+The runtime still supports event flows around:
+
+- reactions
+- poll updates
+- message edits
+
+This is another reason the current `process-message` path was updated only where necessary.
+
+## Deep-dive: device and browser behavior
+
+Device identity matters more than many wrappers admit. In this fork it is especially relevant because the project already uses browser and device strings in a more opinionated way.
+
+### Browser helper examples
+
+```js
+const { Browsers } = require('@neelegirl/baileys')
+
+const webProfile = Browsers.ubuntu('Neelegirl')
+const desktopProfile = Browsers.macOS('Desktop')
+const mobileStyleProfile = Browsers.iOS('Neelegirl iOS')
+```
+
+### `getPlatformId`
+
+The compatibility export `getPlatformId` exists so consumers do not have to guess how platform names map into the pairing flow.
+
+```js
+const { getPlatformId } = require('@neelegirl/baileys')
+
+console.log(getPlatformId('Chrome'))
+console.log(getPlatformId('Desktop'))
+```
+
+### Why not flatten device logic
+
+During maintenance, device logic was not "simplified" because doing that would risk losing:
+
+- Web labels
+- Desktop labels
+- iOS labels
+- Android labels
+- hosted PN and hosted LID distinctions
+
+### Device-aware identity helpers
+
+```js
+const {
+  jidDecode,
+  transferDevice
+} = require('@neelegirl/baileys')
+
+const from = '491234567890:5@s.whatsapp.net'
+const to = '1234567890@lid'
+
+console.log(jidDecode(from))
+console.log(transferDevice(from, to))
+```
+
+### Practical device matrix
+
+| Concern | Why it matters |
+|---|---|
+| browser string | affects how the client is presented |
+| platform id | used in pairing-related flows |
+| desktop-like browser | can influence history sync behavior |
+| hosted device space | matters for some LID and hosted identity transitions |
+
+## Deep-dive: JID and LID handling
+
+One of the biggest reasons to maintain this fork carefully is identity handling.
+
+### Common identity spaces
+
+| Space | Example |
+|---|---|
+| PN user | `491234567890@s.whatsapp.net` |
+| LID user | `1234567890@lid` |
+| hosted PN | `491234567890:99@hosted` |
+| hosted LID | `1234567890:99@hosted.lid` |
+
+### Helpers exposed by the current package
+
+- `jidDecode`
+- `jidEncode`
+- `jidNormalizedUser`
+- `isPnUser`
+- `isLidUser`
+- `isHostedPnUser`
+- `isHostedLidUser`
+- `getServerFromDomainType`
+- `transferDevice`
+- `WAJIDDomains`
+
+### Example: decode and route by identity type
+
+```js
+const {
+  jidDecode,
+  isPnUser,
+  isLidUser,
+  isHostedPnUser,
+  isHostedLidUser
+} = require('@neelegirl/baileys')
+
+function classify(jid) {
+  return {
+    jid,
+    decoded: jidDecode(jid),
+    pn: !!isPnUser(jid),
+    lid: !!isLidUser(jid),
+    hostedPn: !!isHostedPnUser(jid),
+    hostedLid: !!isHostedLidUser(jid)
+  }
+}
+```
+
+### Example: server from domain type
+
+```js
+const {
+  WAJIDDomains,
+  getServerFromDomainType
+} = require('@neelegirl/baileys')
+
+console.log(getServerFromDomainType('s.whatsapp.net', WAJIDDomains.WHATSAPP))
+console.log(getServerFromDomainType('s.whatsapp.net', WAJIDDomains.LID))
+console.log(getServerFromDomainType('s.whatsapp.net', WAJIDDomains.HOSTED))
+console.log(getServerFromDomainType('s.whatsapp.net', WAJIDDomains.HOSTED_LID))
+```
+
+### Why this matters to bots
+
+If your bot logs sender ids, checks participants, stores device metadata, or combines phone-number and LID records, identity mismatches will show up quickly unless the JID layer is handled carefully.
+
+That is exactly why:
+
+- the local `jid-utils` was extended
+- history sync now collects LID-to-PN mapping data
+- session migration helpers now exist in the signal repository
+
+## Deep-dive: history sync behavior
+
+The current local package now handles history sync more consistently with the existing socket expectations.
+
+### What is processed
+
+- conversations
+- contacts
+- messages
+- `phoneNumberToLidMappings`
+- inline bootstrap payloads when present
+
+### What gets emitted
+
+The important event remains:
+
+```js
+sock.ev.on('messaging-history.set', (data) => {
+  console.log(data)
+})
+```
+
+### Example: inspect incoming history batches
+
+```js
+sock.ev.on('messaging-history.set', ({ chats, contacts, messages, lidPnMappings, isLatest }) => {
+  console.log({
+    chats: chats.length,
+    contacts: contacts.length,
+    messages: messages.length,
+    lidPnMappings: lidPnMappings?.length || 0,
+    isLatest
+  })
+})
+```
+
+### Why the mapping part matters
+
+If you maintain your own sender normalization or account mapping layer, the `lidPnMappings` portion can help reconcile:
+
+- phone-number identity space
+- LID identity space
+- device-level migration paths
+
+## Cookbook: common tasks
+
+### Send text
+
+```js
+await sock.sendMessage(jid, { text: 'hello' })
+```
+
+### Send image with caption
+
+```js
+await sock.sendMessage(jid, {
+  image: { url: './image.jpg' },
+  caption: 'caption'
+})
+```
+
+### Send video
+
+```js
+await sock.sendMessage(jid, {
+  video: { url: './video.mp4' },
+  caption: 'video'
+})
+```
+
+### Send document
+
+```js
+await sock.sendMessage(jid, {
+  document: { url: './report.pdf' },
+  mimetype: 'application/pdf',
+  fileName: 'report.pdf'
+})
+```
+
+### Send sticker
+
+```js
+await sock.sendMessage(jid, {
+  sticker: { url: './sticker.webp' }
+})
+```
+
+### Send location
+
+```js
+await sock.sendMessage(jid, {
+  location: {
+    degreesLatitude: 52.52,
+    degreesLongitude: 13.405
+  }
+})
+```
+
+### Send contact
+
+```js
+const vcard = [
+  'BEGIN:VCARD',
+  'VERSION:3.0',
+  'FN:Example Contact',
+  'TEL;type=CELL;type=VOICE;waid=491234567890:+49 123 4567890',
+  'END:VCARD'
+].join('\n')
+
+await sock.sendMessage(jid, {
+  contacts: {
+    displayName: 'Example Contact',
+    contacts: [{ vcard }]
+  }
+})
+```
+
+### Send reaction
+
+```js
+await sock.sendMessage(jid, {
+  react: {
+    text: '❤',
+    key: message.key
+  }
+})
+```
+
+### Remove reaction
+
+```js
+await sock.sendMessage(jid, {
+  react: {
+    text: '',
+    key: message.key
+  }
+})
+```
+
+### Edit a message
+
+```js
+const sent = await sock.sendMessage(jid, { text: 'draft' })
+
+await sock.sendMessage(jid, {
+  text: 'final text',
+  edit: sent.key
+})
+```
+
+### Delete for everyone
+
+```js
+await sock.sendMessage(jid, {
+  delete: message.key
+})
+```
+
+### Mention a user
+
+```js
+await sock.sendMessage(jid, {
+  text: '@491234567890 hello',
+  mentions: ['491234567890@s.whatsapp.net']
+})
+```
+
+### Forward a message
+
+```js
+await sock.sendMessage(jid, {
+  forward: originalMessage
+})
+```
+
+### Send poll
+
+```js
+await sock.sendMessage(jid, {
+  poll: {
+    name: 'Choose one',
+    values: ['A', 'B', 'C'],
+    selectableCount: 1
+  }
+})
+```
+
+## Group and community notes
+
+The current fork still exposes the usual group-oriented socket methods, and the event layer keeps its extended handling for participant and community metadata.
+
+### Example: create a group
+
+```js
+const group = await sock.groupCreate('Example Group', [
+  '491111111111@s.whatsapp.net',
+  '492222222222@s.whatsapp.net'
+])
+
+console.log(group.id)
+```
+
+### Example: add participants
+
+```js
+await sock.groupParticipantsUpdate(
+  group.id,
+  ['493333333333@s.whatsapp.net'],
+  'add'
+)
+```
+
+### Example: change subject
+
+```js
+await sock.groupUpdateSubject(group.id, 'New Subject')
+```
+
+### Example: change description
+
+```js
+await sock.groupUpdateDescription(group.id, 'New Description')
+```
+
+### Example: fetch metadata
+
+```js
+const metadata = await sock.groupMetadata(group.id)
+console.log(metadata.subject)
+```
+
+### Event surfaces that matter here
+
+- `groups.update`
+- `group-participants.update`
+- `group.join-request`
+- `group.member-tag.update`
+- `communities.update`
+
+### Why the fork keeps custom group handling
+
+The local project already has richer handling around:
+
+- group author info
+- participant alternatives
+- community-specific stubs
+- label changes
+
+That is why those paths were preserved instead of normalized down to a simpler generic structure.
+
+## Event reference
+
+The package uses the event-emitter style surface exposed through `sock.ev`.
+
+### High-value events
+
+| Event | Typical use |
+|---|---|
+| `connection.update` | login, reconnect, QR lifecycle |
+| `creds.update` | persist auth state |
+| `messages.upsert` | incoming messages |
+| `messages.update` | edits, receipts, state changes |
+| `messages.reaction` | reaction handling |
+| `messaging-history.set` | first sync and history batches |
+| `contacts.update` | contact refresh |
+| `chats.update` | chat state changes |
+| `groups.update` | group metadata changes |
+| `group-participants.update` | participant changes |
+
+### Example: connection update
+
+```js
+sock.ev.on('connection.update', (update) => {
+  const { connection, qr, isNewLogin, lastDisconnect } = update
+
+  if (qr) {
+    console.log('qr available')
+  }
+
+  if (isNewLogin) {
+    console.log('new login established')
+  }
+
+  if (connection === 'close') {
+    console.log(lastDisconnect?.error)
+  }
+})
+```
+
+### Example: messages upsert
+
+```js
+sock.ev.on('messages.upsert', ({ messages, type }) => {
+  console.log(type, messages.length)
+})
+```
+
+### Example: group participants update
+
+```js
+sock.ev.on('group-participants.update', (event) => {
+  console.log({
+    id: event.id,
+    author: event.author,
+    action: event.action,
+    participants: event.participants
+  })
+})
+```
+
+### Example: group join requests
+
+```js
+sock.ev.on('group.join-request', (event) => {
+  console.log(event)
+})
+```
+
+### Example: reactions
+
+```js
+sock.ev.on('messages.reaction', (items) => {
+  for (const item of items) {
+    console.log(item.reaction)
+  }
+})
+```
+
+## Logging notes
+
+The package continues to work with a `pino`-style logger object. In practice:
+
+- quiet logs are appropriate for production wrappers
+- `debug` is helpful when exploring socket flow
+- `trace` is useful when inspecting binary-node behavior and protocol details
+
+### Example
+
+```js
+const pino = require('pino')
+
+const sock = makeWASocket({
+  version,
+  auth: state,
+  logger: pino({ level: 'info' }),
+  browser: Browsers.ubuntu('Neelegirl'),
+  printQRInTerminal: true
+})
+```
+
+### Why logs were preserved
+
+Neelegirl-specific logging output and watch behavior were explicitly treated as protected. The goal was not to "prettify" logs at the cost of losing operational context.
+
+## Update notice
+
+This package already contains a runtime npm-version check in the current Neelegirl fork.
+
+### What it really does
+
+- it checks the npm registry
+- it does not self-update
+- it prints a hint only
+- it is intentionally lightweight
+
+### When it appears
+
+In the current local fork, the update notice is tied to the existing connection and QR-related flow, and it is designed to run once per process.
+
+### Realistic expectation
+
+If a newer version exists, you still update manually:
+
+```bash
+npm install @neelegirl/baileys@latest
+```
+
+This is the realistic behavior. The package does not automatically replace files in your project.
+
+## Troubleshooting
+
+### QR is not appearing
+
+Check:
+
+- `printQRInTerminal: true`
+- your auth folder is not already fully logged in
+- the socket is actually being started
+- your terminal is not swallowing QR output
+
+### Pairing code does not return
+
+Check:
+
+- `printQRInTerminal` is disabled for pairing flow
+- the phone number is passed without `+`
+- the session is not already registered
+
+### Messages are not sending after reconnect
+
+Check:
+
+- auth state persistence
+- key-store persistence
+- `creds.update` listener
+- whether your custom store is actually writing signal keys back
+
+### Sender ids look inconsistent
+
+Check whether you are mixing:
+
+- PN ids
+- LID ids
+- hosted PN ids
+- hosted LID ids
+
+Normalize before storing or comparing.
+
+### History sync looks incomplete
+
+Check:
+
+- `syncFullHistory`
+- browser profile choice
+- first-login behavior versus reconnect behavior
+- whether you are handling `messaging-history.set`
+
+## FAQ
+
+### Is this the official Baileys package?
+
+No. It is a Neelegirl-maintained fork.
+
+### Is it based on public WhiskeySockets/Baileys?
+
+Yes, but selectively and conservatively.
+
+### Does it preserve the custom QR flow?
+
+Yes.
+
+### Does it preserve `NEELE` message IDs?
+
+Yes.
+
+### Does it mirror every upstream internal file?
+
+No.
+
+### Does it include a CLI?
+
+No.
+
+### Does it auto-update itself?
+
+No. It can show an update hint, but updating remains manual.
+
+### Should I use this instead of upstream for Neelegirl projects?
+
+If your project depends on the current Neelegirl-specific runtime behavior, yes.
+
+### Can I still access lower-level helpers?
+
+Yes. The package exports a broad set of utilities and socket-related helpers.
+
+### Why not just overwrite everything with upstream?
+
+Because that would risk breaking project-specific runtime behavior that already exists locally.
+
+### Why are LID helpers emphasized so much?
+
+Because identity handling is one of the areas most likely to cause subtle regressions in message processing, logging, and sender tracking.
+
+## Configuration patterns
+
+This section is intentionally verbose because configuration details are where many WhatsApp Web client issues begin.
+
+### Minimal practical config
+
+```js
+const sock = makeWASocket({
+  version,
+  auth: state,
+  browser: Browsers.ubuntu('Neelegirl'),
+  printQRInTerminal: true
+})
+```
+
+### Quiet production-oriented config
+
+```js
+const pino = require('pino')
+
+const sock = makeWASocket({
+  version,
+  auth: state,
+  browser: Browsers.windows('Neelegirl Bot'),
+  printQRInTerminal: false,
+  logger: pino({ level: 'silent' }),
+  markOnlineOnConnect: false,
+  syncFullHistory: false
+})
+```
+
+### Store-aware config
+
+```js
+const sock = makeWASocket({
+  version,
+  auth: state,
+  browser: Browsers.macOS('Desktop'),
+  printQRInTerminal: true,
+  getMessage: async (key) => {
+    return store.loadMessage(key.remoteJid, key.id)
+  },
+  cachedGroupMetadata: async (jid) => {
+    return groupCache.get(jid)
+  }
+})
+```
+
+### Config checklist
+
+| Question | Why to check it |
+|---|---|
+| did you pass `auth` | required for login state |
+| did you persist `creds.update` | prevents key drift |
+| did you choose an appropriate `browser` | affects presentation and sometimes sync behavior |
+| did you define `getMessage` if needed | helps retry and recovery flows |
+| did you define `cachedGroupMetadata` if group-heavy | reduces repeated metadata fetches |
+
+## Auth and persistence patterns
+
+### Multi-file auth state
+
+This is usually the easiest place to start:
+
+```js
+const { state, saveCreds } = await useMultiFileAuthState('./auth_info')
+
+const sock = makeWASocket({
+  version,
+  auth: state,
+  browser: Browsers.ubuntu('Neelegirl'),
+  printQRInTerminal: true
+})
+
+sock.ev.on('creds.update', saveCreds)
+```
+
+### Single-file auth state
+
+```js
+const { state, saveCreds } = await useSingleFileAuthState('./auth.json')
+
+const sock = makeWASocket({
+  version,
+  auth: state,
+  browser: Browsers.ubuntu('Neelegirl'),
+  printQRInTerminal: true
+})
+
+sock.ev.on('creds.update', saveCreds)
+```
+
+### Mongo-style helper
+
+If your project uses the local helper for mongo-backed auth state:
+
+```js
+const { state, saveCreds } = await useMongoFileAuthState(mongoCollection)
+```
+
+### Custom persistence rules
+
+If you write your own auth store:
+
+- persist credentials
+- persist signal keys
+- persist updates promptly
+- do not drop `creds.update`
+- do not ignore key mutations
+
+## Store usage
+
+The package still exports `makeInMemoryStore` for simple local state handling.
+
+### Example
+
+```js
+const pino = require('pino')
+const { makeInMemoryStore } = require('@neelegirl/baileys')
+
+const store = makeInMemoryStore({
+  logger: pino({ level: 'silent' })
+})
+
+store.bind(sock.ev)
+```
+
+### Typical uses
+
+- quick development persistence
+- message lookup for retry helpers
+- chat cache
+- contact cache
+
+### Caveat
+
+For serious production systems, build a proper persistent store instead of keeping too much history only in memory.
+
+## More cookbook examples
+
+### Mark messages as read
+
+```js
+await sock.readMessages([message.key])
+```
+
+### Update presence
+
+```js
+await sock.sendPresenceUpdate('available', jid)
+await sock.sendPresenceUpdate('unavailable', jid)
+```
+
+### Subscribe to another user's presence
+
+```js
+await sock.presenceSubscribe(jid)
+```
+
+### Fetch profile picture
+
+```js
+const url = await sock.profilePictureUrl(jid, 'image')
+console.log(url)
+```
+
+### Fetch status
+
+```js
+const status = await sock.fetchStatus(jid)
+console.log(status)
+```
+
+### Check if a number is on WhatsApp
+
+```js
+const [result] = await sock.onWhatsApp('491234567890@s.whatsapp.net')
+console.log(result)
+```
+
+### Run a USync query
+
+```js
+const {
+  USyncQuery,
+  USyncUser
+} = require('@neelegirl/baileys')
+
+const query = new USyncQuery()
+  .withContactProtocol()
+  .withUser(new USyncUser().withPhone('+491234567890'))
+
+const result = await sock.executeUSyncQuery(query)
+console.log(result)
+```
+
+### Fetch group invite code
+
+```js
+const code = await sock.groupInviteCode(groupId)
+console.log(code)
+```
+
+### Accept invite
+
+```js
+const joined = await sock.groupAcceptInvite(code)
+console.log(joined)
+```
+
+### Update profile status
+
+```js
+await sock.updateProfileStatus('hello from neelegirl')
+```
+
+### Update profile name
+
+```js
+await sock.updateProfileName('Neelegirl Bot')
+```
+
+## Architecture notes
+
+This local package can be thought of in layers:
+
+| Layer | Responsibility |
+|---|---|
+| socket layer | connection, noise, login, QR, pairing |
+| utils layer | message building, media handling, parsing, helpers |
+| binary layer | JID parsing and node encoding/decoding |
+| signal layer | session crypto, sender keys, LID mapping |
+| store layer | optional in-memory cache and helpers |
+
+### Why the signal layer mattered in this maintenance pass
+
+The socket already expected LID-aware signal helpers, but the older local `libsignal.js` did not fully provide them. That mismatch was one of the most important actual runtime corrections in the recent update.
+
+## Automatic update note
+
+This package can show an update hint, but it does not auto-patch your installation.
+
+### Realistic behavior summary
+
+| Behavior | Status |
+|---|---|
+| check registry | yes |
+| run once per process | yes |
+| self-update code | no |
+| replace files automatically | no |
+| tell you what to run | yes |
+
+### Manual update commands
+
+```bash
+npm install @neelegirl/baileys@latest
+```
+
+```bash
+yarn add @neelegirl/baileys@latest
+```
+
+### Why not self-update
+
+Auto-replacing package files inside an active bot environment would be risky and surprising. A hint is realistic. Silent mutation of dependencies is not.
+
+## Glossary
+
+### PN
+
+Phone-number identity space, typically `@s.whatsapp.net`.
+
+### LID
+
+Linked identity space, typically `@lid`.
+
+### hosted PN
+
+Hosted phone-number identity space, often seen with device-specific hosted forms.
+
+### hosted LID
+
+Hosted LID identity space, often seen when identity and hosted-device concerns intersect.
+
+### `participantAlt`
+
+Project-specific alternate participant metadata preserved in the local fork.
+
+### `remoteJidAlt`
+
+Project-specific alternate remote jid metadata preserved in the local fork.
+
+### `senderNormalized`
+
+A generic phrase used in many bot projects to refer to the stable sender representation after identity reconciliation.
+
+## Project policy
+
+This fork intentionally prioritizes:
+
+- stable behavior for existing Neelegirl consumers
+- conservative compatibility updates
+- readable maintenance over flashy churn
+- truthful documentation over exaggerated claims
+
+It intentionally avoids:
+
+- blind upstream overwrite
+- destructive export-map tightening
+- rewriting protected project logic just to look more "modern"
+
+## Documentation philosophy
+
+This README is intentionally longer than a minimal package page because users of this fork usually need:
+
+- a clear explanation of why the fork exists
+- reassurance about what custom logic is protected
+- a practical guide for auth, QR, pairing, and message handling
+- a realistic statement of what is and is not updated automatically
+
+## Release notes
+
+### 2.1.8
+
+- runtime hotfix release for CommonJS `lru-cache` compatibility in the current Neelegirl environment
+- fixed constructor resolution used by LID mapping and retry cache initialization
+- dependency range aligned to `@neelegirl/libsignal@^1.0.12`
+
+### 2.1.7
+
+- documentation expansion release
+- Baileys README now includes deep operational guidance and realistic update behavior notes
+- dependency range aligned to `@neelegirl/libsignal@^1.0.11`
 
 ### 2.1.6
 

package/lib/Signal/libsignal.js

@@ -4,7 +4,8 @@ Object.defineProperty(exports, "__esModule", { value: true })
 
 const libsignal = require("@neelegirl/libsignal")
 const { PreKeyWhisperMessage } = require("@neelegirl/libsignal/src/protobufs")
-const { LRUCache } = require("lru-cache")
+const LRUCacheModule = require("lru-cache")
+const LRUCache = LRUCacheModule.LRUCache || LRUCacheModule
 const WASignalGroup_1 = require("./WASignalGroup")
 const lid_mapping_1 = require("./lid-mapping")
 const Utils_1 = require("../Utils")

package/lib/Signal/lid-mapping.js

@@ -2,7 +2,8 @@
 
 Object.defineProperty(exports, "__esModule", { value: true })
 
-const { LRUCache } = require("lru-cache")
+const LRUCacheModule = require("lru-cache")
+const LRUCache = LRUCacheModule.LRUCache || LRUCacheModule
 const WABinary_1 = require("../WABinary")
 
 class LIDMappingStore {

package/lib/Utils/message-retry-manager.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MessageRetryManager = void 0;
 const lru_cache_1 = require("lru-cache");
+const LRUCache = lru_cache_1.LRUCache || lru_cache_1;
 /** Number of sent messages to cache in memory for handling retry receipts */
 const RECENT_MESSAGES_SIZE = 512;
 const MESSAGE_KEY_SEPARATOR = '\u0000';
@@ -11,7 +12,7 @@ const PHONE_REQUEST_DELAY = 3000;
 class MessageRetryManager {
     constructor(logger, maxMsgRetryCount) {
         this.logger = logger;
-        this.recentMessagesMap = new lru_cache_1.LRUCache({
+        this.recentMessagesMap = new LRUCache({
             max: RECENT_MESSAGES_SIZE,
             ttl: 5 * 60 * 1000,
             ttlAutopurge: true,
@@ -24,11 +25,11 @@ class MessageRetryManager {
             }
         });
         this.messageKeyIndex = new Map();
-        this.sessionRecreateHistory = new lru_cache_1.LRUCache({
+        this.sessionRecreateHistory = new LRUCache({
             ttl: RECREATE_SESSION_TIMEOUT * 2,
             ttlAutopurge: true
         });
-        this.retryCounters = new lru_cache_1.LRUCache({
+        this.retryCounters = new LRUCache({
             ttl: 15 * 60 * 1000,
             ttlAutopurge: true,
             updateAgeOnGet: true
@@ -176,4 +177,3 @@ exports.MessageRetryManager = MessageRetryManager;
 //# sourceMappingURL=message-retry-manager.js.map
 
 
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neelegirl/baileys",
-  "version": "2.1.6",
+  "version": "2.1.8",
   "description": "CommonJS Neelegirl Baileys fork with preserved QR/NEELE logic and selective WhiskeySockets/Baileys compatibility updates",
   "keywords": [
     "whatsapp",
@@ -44,7 +44,7 @@
     "@adiwajshing/keyed-db": "^0.2.4",
     "@cacheable/node-cache": "^1.5.4",
     "@hapi/boom": "^9.1.3",
-    "@neelegirl/libsignal": "^1.0.9",
+    "@neelegirl/libsignal": "^1.0.12",
     "async-mutex": "^0.5.0",
     "audio-decode": "^2.1.3",
     "axios": "^1.3.3",