@neelegirl/baileys 2.1.5 → 2.1.7

package/README.md

@@ -1,215 +1,1637 @@
-<div align="center">
+<div align="center">
 
 # @neelegirl/baileys
 
-### CJS-compatible WhatsApp Web API foundation for the Neelegirl ecosystem
+### CommonJS WhatsApp Web runtime for Neelegirl projects
+### Conservative merge strategy based on WhiskeySockets/Baileys
 
-[![Version](https://img.shields.io/badge/Version-2.1.5-ff69b4?style=for-the-badge)](https://www.npmjs.com/package/@neelegirl/baileys)
-[![Upstream](https://img.shields.io/badge/Upstream-WhiskeySockets%2FBaileys%207.0.0--rc.9-9b59b6?style=for-the-badge)](https://github.com/WhiskeySockets/Baileys)
-[![Node](https://img.shields.io/badge/Node-20%2B-2ea043?style=for-the-badge&logo=node.js)](https://nodejs.org)
-[![License](https://img.shields.io/badge/License-MIT-f97316?style=for-the-badge)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@neelegirl/baileys?style=for-the-badge&color=ff69b4&logo=npm)](https://www.npmjs.com/package/@neelegirl/baileys)
+[![node](https://img.shields.io/badge/node-%3E%3D20-2ea043?style=for-the-badge&logo=node.js)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-f97316?style=for-the-badge)](LICENSE)
+[![runtime](https://img.shields.io/badge/runtime-CommonJS-2563eb?style=for-the-badge)](https://www.npmjs.com/package/@neelegirl/baileys)
+[![reference](https://img.shields.io/badge/reference-WhiskeySockets%2FBaileys-111827?style=for-the-badge)](https://github.com/WhiskeySockets/Baileys)
+
+---
 
 <p align="center">
-  <img src="https://files.catbox.moe/phppor.JPG" width="760" alt="Neelegirl Baileys Header" />
+  <img src="https://files.catbox.moe/phppor.JPG" width="760" alt="@neelegirl/baileys" />
 </p>
 
-| Paket | Version | Basis |
+| Package | Version | Main goal |
 |---|---:|---|
-| `@neelegirl/baileys` | `2.1.5` | `WhiskeySockets/Baileys v7.0.0-rc.9` |
+| `@neelegirl/baileys` | `2.1.7` | Stable Neelegirl fork with preserved project-specific runtime behavior |
 
-[Installation](#installation) · [Quickstart](#quickstart) · [Funktionslogik](#funktionslogik) · [Aenderungen](#aenderungen--hinweise)
+[Installation](#installation) · [Quickstart](#quickstart) · [Protected logic](#protected-logic) · [Device and LID notes](#device-and-lid-notes) · [Verified exports](#verified-exports) · [Release notes](#release-notes)
 
 </div>
 
 ---
 
-## Inhaltsverzeichnis
+## Table of Contents
 
-- [Uebersicht](#uebersicht)
+- [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)
 - [Installation](#installation)
+- [Imports](#imports)
 - [Quickstart](#quickstart)
-- [Funktionslogik](#funktionslogik)
-- [Aenderungen und Hinweise](#aenderungen--hinweise)
-- [libsignal im Stack](#libsignal-im-stack)
-- [Word2Web Hinweise](#word2web-hinweise)
-- [Kompatibilitaet und Grenzen](#kompatibilitaet-und-grenzen)
-- [Changelog](#changelog)
-- [Legal](#legal)
+- [Session storage](#session-storage)
+- [Socket configuration notes](#socket-configuration-notes)
+- [Messages and media](#messages-and-media)
+- [Device and LID notes](#device-and-lid-notes)
+- [Event notes](#event-notes)
+- [Verified exports](#verified-exports)
+- [Known limits](#known-limits)
+- [Release notes](#release-notes)
+- [Disclaimer](#disclaimer)
 
----
+## Overview
 
-## Uebersicht
+`@neelegirl/baileys` is the local CommonJS-oriented Neelegirl fork of Baileys used in this stack. It is meant to keep existing Neelegirl-specific behavior stable while still absorbing compatible fixes from the public WhiskeySockets/Baileys project where that improves correctness.
 
-`@neelegirl/baileys` ist die CJS-orientierte Laufzeitbasis fuer das Neelegirl-Setup. Es uebernimmt die Socket-, Event-, Auth- und Message-Mechanik und bleibt dabei kompatibel zu bestehenden `require()`-Projekten.
+This package was rechecked against the public WhiskeySockets/Baileys repository on `2026-03-19`. The merge strategy is conservative by design:
 
-Wichtige Punkte aus den bisherigen Projekt-READMEs, auf den echten Code gemappt:
+- keep working Neelegirl runtime behavior
+- adopt compatible fixes
+- avoid blind upstream replacement
+- avoid destructive refactors in project-critical paths
 
-- QR-Flow bleibt wie im Projekt vorgesehen erhalten.
-- Message-ID-Signatur mit `NEELE` bleibt erhalten.
-- LID/JID-bezogene Verarbeitung ist in den Socket/Signal-Pfaden aktiv.
-- npm-Update-Check ist enthalten (bei QR-Flow, nur einmal pro Prozess).
-- Aktuelle lokale WA-Web-Version: `[2, 3000, 1035194821]`.
+## Why this fork exists
 
----
+The local package differs from upstream for practical reasons:
+
+| Area | Intent |
+|---|---|
+| Module format | Keep CommonJS entrypoints and local consumer compatibility |
+| QR flow | Preserve the existing project-specific QR behavior |
+| Message IDs | Preserve `NEELE`-specific message-ID behavior |
+| Device mapping | Keep project-specific platform and device labeling logic |
+| Logging and watch behavior | Avoid breaking existing Neelegirl operational workflows |
+| LID and JID handling | Extend carefully where current Baileys behavior improves compatibility |
+
+## Protected logic
+
+The following logic was explicitly treated as protected during maintenance:
+
+- QR-code generation and QR lifecycle
+- `NEELE` message-ID generation and related custom handling
+- existing Neelegirl branding and log output
+- existing device, watch, and platform-specific behavior
+- existing custom community and message-stub handling
+- existing message-type behavior for conversation, extended text, media, and context handling
+
+Nothing in those areas was blindly replaced with upstream code.
+
+## What was updated in 2.1.6
+
+### Runtime compatibility
+
+- fixed the mismatch between `socket.js` expectations and the local Signal repository implementation
+- added the missing runtime LID mapping store
+- aligned session helpers required by the current local socket logic:
+  - `lidMapping`
+  - `validateSession`
+  - `deleteSession`
+  - `migrateSession`
+
+### History and identity handling
+
+- history sync processing now collects `phoneNumberToLidMappings`
+- inline bootstrap payloads are handled
+- LID migration sync messages are processed conservatively
+- session migration can now follow PN to LID transitions more cleanly
+
+### JID and device helpers
+
+- restored and exposed helpers needed by newer Baileys compatibility work:
+  - `WAJIDDomains`
+  - `getServerFromDomainType`
+  - `isPnUser`
+  - `isJidMetaAI`
+  - `transferDevice`
+- added a compatibility `browser-utils` re-export for `Browsers` and `getPlatformId`
+
+### Typings and docs
+
+- refreshed multiple `.d.ts` files to match the actual current runtime more closely
+- removed false README claims from older documentation
+- replaced stale README imagery with the requested current project image
 
 ## Installation
 
+Use npm:
+
 ```bash
 npm install @neelegirl/baileys
 ```
 
-Import:
+Use yarn:
+
+```bash
+yarn add @neelegirl/baileys
+```
+
+Runtime requirement:
+
+```text
+Node.js >= 20
+```
+
+## Imports
+
+CommonJS:
 
 ```js
-// CommonJS
+const makeWASocket = require('@neelegirl/baileys').default
 const {
-  default: makeWASocket,
-  useMultiFileAuthState,
-  fetchLatestBaileysVersion,
-  DisconnectReason,
   Browsers,
+  DisconnectReason,
+  fetchLatestBaileysVersion,
+  useMultiFileAuthState
 } = require('@neelegirl/baileys')
-
-// ESM (namespace import auf CJS-Export)
-import * as baileys from '@neelegirl/baileys'
 ```
 
----
+ESM:
+
+```js
+import makeWASocket, {
+  Browsers,
+  DisconnectReason,
+  fetchLatestBaileysVersion,
+  useMultiFileAuthState
+} from '@neelegirl/baileys'
+```
 
 ## Quickstart
 
+### Start with QR
+
 ```js
+const makeWASocket = require('@neelegirl/baileys').default
 const {
-  default: makeWASocket,
-  useMultiFileAuthState,
-  fetchLatestBaileysVersion,
-  DisconnectReason,
   Browsers,
+  DisconnectReason,
+  fetchLatestBaileysVersion,
+  useMultiFileAuthState
 } = require('@neelegirl/baileys')
 
-async function startBot() {
+async function start() {
   const { state, saveCreds } = await useMultiFileAuthState('./auth_info')
   const { version } = await fetchLatestBaileysVersion()
 
   const sock = makeWASocket({
-    auth: state,
     version,
-    printQRInTerminal: true,
-    browser: Browsers.ubuntu('Chrome'),
+    auth: state,
+    browser: Browsers.ubuntu('Neelegirl'),
+    printQRInTerminal: true
   })
 
   sock.ev.on('creds.update', saveCreds)
 
   sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+    if (connection === 'open') {
+      console.log('connected')
+    }
+
     if (connection === 'close') {
       const code = lastDisconnect?.error?.output?.statusCode
-      if (code !== DisconnectReason.loggedOut) {
-        startBot()
+      const shouldReconnect = code !== DisconnectReason.loggedOut
+      if (shouldReconnect) {
+        start()
       }
-      return
-    }
-
-    if (connection === 'open') {
-      console.log('Connected to WhatsApp')
     }
   })
 
   sock.ev.on('messages.upsert', async ({ messages }) => {
-    const msg = messages?.[0]
-    const text = msg?.message?.conversation || msg?.message?.extendedTextMessage?.text || ''
-    const jid = msg?.key?.remoteJid
-    if (jid && text.toLowerCase() === 'ping') {
-      await sock.sendMessage(jid, { text: 'pong' })
+    const msg = messages[0]
+    const text =
+      msg?.message?.conversation ||
+      msg?.message?.extendedTextMessage?.text ||
+      ''
+
+    if (text.toLowerCase() === 'ping') {
+      await sock.sendMessage(msg.key.remoteJid, { text: 'pong' })
     }
   })
 }
 
-startBot().catch(console.error)
+start().catch(console.error)
 ```
 
----
+### Start with pairing code
+
+```js
+const makeWASocket = require('@neelegirl/baileys').default
+const {
+  Browsers,
+  fetchLatestBaileysVersion,
+  useMultiFileAuthState
+} = require('@neelegirl/baileys')
+
+async function startPairing() {
+  const { state, saveCreds } = await useMultiFileAuthState('./auth_pairing')
+  const { version } = await fetchLatestBaileysVersion()
+
+  const sock = makeWASocket({
+    version,
+    auth: state,
+    browser: Browsers.windows('Neelegirl'),
+    printQRInTerminal: false
+  })
 
-## Funktionslogik
+  sock.ev.on('creds.update', saveCreds)
 
-### Runtime und API
+  if (!sock.authState.creds.registered) {
+    const code = await sock.requestPairingCode('491234567890')
+    console.log('pairing code:', code)
+  }
+}
 
-- Exporte aus `lib/index.js`:
-  - `default` / `makeWASocket`
-  - `Utils`, `Types`, `Store`, `Defaults`, `WABinary`, `WAM`, `WAUSync`, `WAProto`
-- CJS-first Struktur (`main: lib/index.js`, `types: lib/index.d.ts`)
+startPairing().catch(console.error)
+```
 
-### Ereignisse und Verbindung
+## Session storage
 
-- `connection.update`, `messages.upsert`, `messages.update`, `creds.update`
-- QR wird ueber den normalen Connection-Update-Flow ausgegeben
-- Reconnect-Steuerung erfolgt ueber Disconnect-Grund (`DisconnectReason`)
+For development, `useMultiFileAuthState(...)` is the easiest storage helper:
 
-### Auth und Session
+```js
+const { state, saveCreds } = await useMultiFileAuthState('./auth_info')
+```
 
-- `useMultiFileAuthState` fuer persistente Session-Dateien
-- Signale/Keys laufen ueber die integrierten Signal-Utilities
+The package also exports:
 
-### Nachrichten und Hilfsfunktionen
+- `useSingleFileAuthState`
+- `useMongoFileAuthState`
+- `makeInMemoryStore`
 
-- `sendMessage` fuer Text/Medien/reaktionen/polls usw.
-- Gruppen-, Community-, Newsletter- und Store-Utilities sind enthalten
-- LID/JID-Helfer (`jidDecode`, `jidEncode`, `isLidUser`) stehen ueber die Utility-Exports zur Verfuegung
+If you build a custom store, the critical rule is simple:
 
----
+- credential updates must be persisted
+- key updates must be persisted
+- ignoring key-store updates will eventually break message delivery
 
-## Aenderungen & Hinweise
+## Socket configuration notes
 
-Diese README uebernimmt die Dokumentationslogik aus den zwei Quell-READMEs und passt sie auf den realen Paketstand an:
+Useful socket options that remain especially relevant in this fork:
 
-- Funktionale Beschreibungen wurden beibehalten und auf echte Exporte reduziert.
-- Historische Hinweise wurden bereinigt, wenn sie veraltete Versionen nannten.
-- Keine nicht nachweisbaren Features aufgenommen.
+| Option | Why it matters |
+|---|---|
+| `auth` | required session state |
+| `version` | WA Web version selection |
+| `browser` | affects platform/device presentation |
+| `printQRInTerminal` | keeps the existing QR path active |
+| `markOnlineOnConnect` | controls online presence behavior |
+| `syncFullHistory` | enables broader history sync requests |
+| `getMessage` | improves retry and message recovery scenarios |
+| `cachedGroupMetadata` | avoids repeated group fetches |
 
-Technisch relevante Punkte:
+Example:
 
-- QR-Logik unveraendert belassen.
-- `NEELE`-Message-ID-Signatur unveraendert belassen.
-- Update-Check auf npm-Registry aktiv.
-- WA-Web-Version-Datei auf aktuellen lokalen Stand aktualisiert.
+```js
+const sock = makeWASocket({
+  version,
+  auth: state,
+  browser: Browsers.macOS('Desktop'),
+  printQRInTerminal: true,
+  markOnlineOnConnect: false,
+  syncFullHistory: true,
+  getMessage: async (key) => {
+    return store.loadMessage(key.remoteJid, key.id)
+  },
+  cachedGroupMetadata: async (jid) => groupCache.get(jid)
+})
+```
 
----
+## Messages and media
+
+### Send a text message
 
-## libsignal im Stack
+```js
+await sock.sendMessage(jid, { text: 'hello' })
+```
 
-`@neelegirl/baileys` nutzt `@neelegirl/libsignal` fuer kryptografische Session-Bausteine (Identity, PreKeys, SessionState, Cipher-Operationen). Das ist die Grundlage fuer stabile Multi-Device-Kommunikation.
+### Reply to a message
 
----
+```js
+await sock.sendMessage(
+  jid,
+  { text: 'this is a reply' },
+  { quoted: originalMessage }
+)
+```
 
-## Word2Web Hinweise
+### Send an image
 
-Es gibt in diesem Paket kein dediziertes Word2Web-Modul. Word2Web-spezifische Logik sollte nur dokumentiert/aktiviert werden, wenn sie in deiner Host-Anwendung wirklich implementiert ist.
+```js
+await sock.sendMessage(jid, {
+  image: { url: './image.jpg' },
+  caption: 'sample'
+})
+```
 
----
+### Send a document
 
-## Kompatibilitaet und Grenzen
+```js
+await sock.sendMessage(jid, {
+  document: { url: './report.pdf' },
+  mimetype: 'application/pdf',
+  fileName: 'report.pdf'
+})
+```
 
-- Node.js: `>=20`
-- CJS-fokussiert, nicht als 1:1-ESM-Upstream-Ersatz dokumentiert
-- Die API ist auf bestehende Neelegirl-Consumer ausgerichtet
+### Send a reaction
 
----
+```js
+await sock.sendMessage(jid, {
+  react: {
+    text: '❤',
+    key: message.key
+  }
+})
+```
 
-## Changelog
+### Download received media
 
-### 2.1.5
+```js
+const { downloadMediaMessage } = require('@neelegirl/baileys')
+
+const buffer = await downloadMediaMessage(
+  message,
+  'buffer',
+  {},
+  { logger: sock.logger, reuploadRequest: sock.updateMediaMessage }
+)
+```
 
-- README inhaltlich mit den Desktop-Quellen zusammengefuehrt (ohne blindes Kopieren)
-- Funktionsbeschreibungen, Nutzungslogik und technische Hinweise auf realen Paketstand gemappt
-- Versions- und Abhaengigkeitsabgleich im Neelegirl-Stack aktualisiert
-- QR-Flow und `NEELE`-Message-ID-Verhalten unveraendert beibehalten
+## Device and LID notes
 
-### 2.1.4
+This fork intentionally does more than just plain PN handling.
 
-- Style-/Layout-Refresh fuer konsistente Projektdokumentation
-- Publish-Metadaten und CJS-Kompatibilitaet nachgezogen
+### Relevant helper exports
 
----
+- `jidDecode`
+- `jidEncode`
+- `jidNormalizedUser`
+- `isPnUser`
+- `isLidUser`
+- `isHostedPnUser`
+- `isHostedLidUser`
+- `transferDevice`
+- `WAJIDDomains`
+
+### Example: inspect a JID
+
+```js
+const { jidDecode } = require('@neelegirl/baileys')
+
+const decoded = jidDecode('491234567890@s.whatsapp.net')
+console.log(decoded)
+```
+
+### Example: preserve device while switching identity space
+
+```js
+const { transferDevice } = require('@neelegirl/baileys')
+
+const result = transferDevice(
+  '491234567890:5@s.whatsapp.net',
+  '1234567890@lid'
+)
+```
+
+### Why this matters here
+
+Neelegirl-specific code in this package already relies on richer identity handling around:
+
+- `remoteJid`
+- `remoteJidAlt`
+- `participant`
+- `participantAlt`
+- sender normalization
+- PN and LID mapping
+- device labeling output
+
+That is why the maintenance work kept those paths intact and only extended compatibility where necessary.
+
+## Event notes
+
+Useful events in the current runtime:
+
+### Connection lifecycle
+
+- `connection.update`
+- `creds.update`
+
+### Message flow
+
+- `messages.upsert`
+- `messages.update`
+- `messages.reaction`
+- `message-receipt.update`
+
+### History and metadata
+
+- `messaging-history.set`
+- `contacts.upsert`
+- `contacts.update`
+- `chats.update`
+
+### Group and community related
+
+- `groups.update`
+- `group-participants.update`
+- `group.join-request`
+- `group.member-tag.update`
+- `communities.update`
+
+### Example
+
+```js
+sock.ev.on('messaging-history.set', ({ chats, contacts, messages, lidPnMappings }) => {
+  console.log({
+    chats: chats.length,
+    contacts: contacts.length,
+    messages: messages.length,
+    lidPnMappings: lidPnMappings?.length || 0
+  })
+})
+```
+
+## Verified exports
+
+The following items were verified in the currently prepared package before publish.
+
+### Socket and auth
+
+- `makeWASocket`
+- `useMultiFileAuthState`
+- `useSingleFileAuthState`
+- `useMongoFileAuthState`
+- `makeInMemoryStore`
+
+### Version and browser helpers
+
+- `fetchLatestBaileysVersion`
+- `fetchLatestWaWebVersion`
+- `Browsers`
+- `getPlatformId`
+
+### JID and identity helpers
+
+- `jidDecode`
+- `jidEncode`
+- `jidNormalizedUser`
+- `isPnUser`
+- `isLidUser`
+- `isHostedPnUser`
+- `isHostedLidUser`
+- `isJidMetaAI`
+- `transferDevice`
+- `WAJIDDomains`
+
+### Message and media helpers
+
+- `downloadMediaMessage`
+- `downloadAndProcessHistorySyncNotification`
+- `processHistoryMessage`
+- `getHistoryMsg`
+- `getContentType`
+- `normalizeMessageContent`
+- `generateWAMessage`
+- `generateWAMessageContent`
+- `generateWAMessageFromContent`
+
+### USync helpers
+
+- `USyncQuery`
+- `USyncUser`
+- `USyncContactProtocol`
+- `USyncLIDProtocol`
+- `USyncDeviceProtocol`
+- `USyncStatusProtocol`
+
+## Known limits
+
+- this package is not a direct one-to-one mirror of every newest upstream internal API
+- 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
+
+## 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.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
+
+- restored runtime consistency between socket logic and Signal repository behavior
+- added local LID mapping store support
+- improved history sync processing for LID and PN mapping capture
+- added current JID helper compatibility exports
+- refreshed typings and README without touching protected QR and `NEELE` logic
+
+### 2.1.5
+
+- previous local package baseline before the current conservative maintenance pass
 
-## Legal
+## Disclaimer
 
-Dieses Projekt ist nicht mit WhatsApp verbunden. Nutzung nur in Uebereinstimmung mit geltendem Recht und Plattformregeln.
+This project is not affiliated with WhatsApp. Use it responsibly. Do not use it for spam, stalking, or abusive automation.