@neelegirl/baileys 2.1.5 → 2.1.6

package/README.md

@@ -1,215 +1,536 @@
-<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.6` | 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
 
-## Funktionslogik
+```js
+const makeWASocket = require('@neelegirl/baileys').default
+const {
+  Browsers,
+  fetchLatestBaileysVersion,
+  useMultiFileAuthState
+} = require('@neelegirl/baileys')
 
-### Runtime und API
+async function startPairing() {
+  const { state, saveCreds } = await useMultiFileAuthState('./auth_pairing')
+  const { version } = await fetchLatestBaileysVersion()
 
-- 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`)
+  const sock = makeWASocket({
+    version,
+    auth: state,
+    browser: Browsers.windows('Neelegirl'),
+    printQRInTerminal: false
+  })
 
-### Ereignisse und Verbindung
+  sock.ev.on('creds.update', saveCreds)
+
+  if (!sock.authState.creds.registered) {
+    const code = await sock.requestPairingCode('491234567890')
+    console.log('pairing code:', code)
+  }
+}
 
-- `connection.update`, `messages.upsert`, `messages.update`, `creds.update`
-- QR wird ueber den normalen Connection-Update-Flow ausgegeben
-- Reconnect-Steuerung erfolgt ueber Disconnect-Grund (`DisconnectReason`)
+startPairing().catch(console.error)
+```
 
-### Auth und Session
+## Session storage
 
-- `useMultiFileAuthState` fuer persistente Session-Dateien
-- Signale/Keys laufen ueber die integrierten Signal-Utilities
+For development, `useMultiFileAuthState(...)` is the easiest storage helper:
 
-### Nachrichten und Hilfsfunktionen
+```js
+const { state, saveCreds } = await useMultiFileAuthState('./auth_info')
+```
 
-- `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
+The package also exports:
 
----
+- `useSingleFileAuthState`
+- `useMongoFileAuthState`
+- `makeInMemoryStore`
 
-## Aenderungen & Hinweise
+If you build a custom store, the critical rule is simple:
 
-Diese README uebernimmt die Dokumentationslogik aus den zwei Quell-READMEs und passt sie auf den realen Paketstand an:
+- credential updates must be persisted
+- key updates must be persisted
+- ignoring key-store updates will eventually break message delivery
 
-- Funktionale Beschreibungen wurden beibehalten und auf echte Exporte reduziert.
-- Historische Hinweise wurden bereinigt, wenn sie veraltete Versionen nannten.
-- Keine nicht nachweisbaren Features aufgenommen.
+## Socket configuration notes
 
-Technisch relevante Punkte:
+Useful socket options that remain especially relevant in this fork:
 
-- 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.
+| 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 |
 
----
+Example:
 
-## libsignal im Stack
+```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)
+})
+```
 
-`@neelegirl/baileys` nutzt `@neelegirl/libsignal` fuer kryptografische Session-Bausteine (Identity, PreKeys, SessionState, Cipher-Operationen). Das ist die Grundlage fuer stabile Multi-Device-Kommunikation.
+## Messages and media
 
----
+### Send a text message
 
-## Word2Web Hinweise
+```js
+await sock.sendMessage(jid, { text: 'hello' })
+```
 
-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.
+### Reply to a message
 
----
+```js
+await sock.sendMessage(
+  jid,
+  { text: 'this is a reply' },
+  { quoted: originalMessage }
+)
+```
+
+### Send an image
 
-## Kompatibilitaet und Grenzen
+```js
+await sock.sendMessage(jid, {
+  image: { url: './image.jpg' },
+  caption: 'sample'
+})
+```
 
-- Node.js: `>=20`
-- CJS-fokussiert, nicht als 1:1-ESM-Upstream-Ersatz dokumentiert
-- Die API ist auf bestehende Neelegirl-Consumer ausgerichtet
+### Send a document
 
----
+```js
+await sock.sendMessage(jid, {
+  document: { url: './report.pdf' },
+  mimetype: 'application/pdf',
+  fileName: 'report.pdf'
+})
+```
 
-## Changelog
+### Send a reaction
 
-### 2.1.5
+```js
+await sock.sendMessage(jid, {
+  react: {
+    text: '❤',
+    key: message.key
+  }
+})
+```
+
+### Download received media
 
-- 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
+```js
+const { downloadMediaMessage } = require('@neelegirl/baileys')
+
+const buffer = await downloadMediaMessage(
+  message,
+  'buffer',
+  {},
+  { logger: sock.logger, reuploadRequest: sock.updateMediaMessage }
+)
+```
 
-### 2.1.4
+## Device and LID notes
 
-- Style-/Layout-Refresh fuer konsistente Projektdokumentation
-- Publish-Metadaten und CJS-Kompatibilitaet nachgezogen
+This fork intentionally does more than just plain PN handling.
 
----
+### 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
+
+## Release notes
+
+### 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.

package/lib/Signal/libsignal.d.ts

@@ -1,4 +1,9 @@
-import { SignalAuthState } from '../Types'
-import { SignalRepository } from '../Types/Signal'
+import { LIDMapping, SignalAuthState } from '../Types'
+import { SignalRepositoryWithLIDStore } from '../Types/Signal'
+import type { ILogger } from '../Utils/logger'
 
-export declare function makeLibSignalRepository(auth: SignalAuthState): SignalRepository
+export declare function makeLibSignalRepository(
+    auth: SignalAuthState,
+    logger: ILogger,
+    pnToLIDFunc?: (jids: string[]) => Promise<LIDMapping[] | undefined>
+): SignalRepositoryWithLIDStore