@neelegirl/baileys 2.1.4 → 2.1.6

package/README.md

@@ -1,23 +1,27 @@
-<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.4-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>
 
-| Package | Latest Version | Upstream Base |
+| Package | Version | Main goal |
 |---|---:|---|
-| `@neelegirl/baileys` | `2.1.4` | `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) · [Feature Overview](#feature-overview) · [Compatibility Notes](#compatibility-notes)
+[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>
 
@@ -25,68 +29,189 @@
 
 ## Table of Contents
 
-- [Why this fork](#why-this-fork)
+- [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)
-- [Feature Overview](#feature-overview)
-- [Compatibility Notes](#compatibility-notes)
-- [Word2Web Notes](#word2web-notes)
-- [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
 
-## Why this fork
+`@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` keeps a CJS-first runtime for projects that depend on `require()` behavior while integrating relevant upstream updates.
+This package was rechecked against the public WhiskeySockets/Baileys repository on `2026-03-19`. The merge strategy is conservative by design:
 
-This fork explicitly keeps two project-critical customizations unchanged:
+- keep working Neelegirl runtime behavior
+- adopt compatible fixes
+- avoid blind upstream replacement
+- avoid destructive refactors in project-critical paths
 
-- QR-code handling logic stays unchanged.
-- Message-ID logic containing `NEELE` stays unchanged.
+## 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
 ```
 
----
+Use yarn:
 
-## Quickstart
+```bash
+yarn add @neelegirl/baileys
+```
+
+Runtime requirement:
+
+```text
+Node.js >= 20
+```
+
+## Imports
+
+CommonJS:
 
 ```js
+const makeWASocket = require('@neelegirl/baileys').default
 const {
-  default: makeWASocket,
-  useMultiFileAuthState,
+  Browsers,
+  DisconnectReason,
   fetchLatestBaileysVersion,
+  useMultiFileAuthState
+} = require('@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 {
   Browsers,
+  DisconnectReason,
+  fetchLatestBaileysVersion,
+  useMultiFileAuthState
 } = require('@neelegirl/baileys')
 
 async function start() {
-  const { state, saveCreds } = await useMultiFileAuthState('./auth')
+  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) start()
+      const shouldReconnect = code !== DisconnectReason.loggedOut
+      if (shouldReconnect) {
+        start()
+      }
     }
+  })
 
-    if (connection === 'open') {
-      console.log('Connected')
+  sock.ev.on('messages.upsert', async ({ messages }) => {
+    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' })
     }
   })
 }
@@ -94,45 +219,318 @@ async function start() {
 start().catch(console.error)
 ```
 
----
+### Start with pairing code
 
-## Feature Overview
+```js
+const makeWASocket = require('@neelegirl/baileys').default
+const {
+  Browsers,
+  fetchLatestBaileysVersion,
+  useMultiFileAuthState
+} = require('@neelegirl/baileys')
 
-- Socket, event, auth, and message APIs from the current local CJS distribution
-- LID/JID handling in send and receive flows
-- Group, community, newsletter, media, and store utilities
-- Optional peers for QR rendering, preview extraction, and image/audio processing
-- Runtime update-check support kept from the current Neelegirl package line
+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
+  })
 
-## Compatibility Notes
+  sock.ev.on('creds.update', saveCreds)
 
-- Runtime target: Node.js `>=20`
-- Module shape: CJS-first (`main: lib/index.js`)
-- Upstream policy: selective backporting from WhiskeySockets/Baileys for compatibility
+  if (!sock.authState.creds.registered) {
+    const code = await sock.requestPairingCode('491234567890')
+    console.log('pairing code:', code)
+  }
+}
 
-If you need strict ESM parity with upstream source layout, migrate consumers to ESM first.
+startPairing().catch(console.error)
+```
 
----
+## Session storage
 
-## Word2Web Notes
+For development, `useMultiFileAuthState(...)` is the easiest storage helper:
 
-No dedicated Word2Web module is shipped in this package. Document or enable Word2Web behavior only in host projects where it is actually implemented.
+```js
+const { state, saveCreds } = await useMultiFileAuthState('./auth_info')
+```
 
----
+The package also exports:
 
-## Changelog
+- `useSingleFileAuthState`
+- `useMongoFileAuthState`
+- `makeInMemoryStore`
 
-### 2.1.4
+If you build a custom store, the critical rule is simple:
 
-- README restyled to match the main project presentation style
-- Package metadata refined for publish consistency
-- Dependency alignment with `@neelegirl/libsignal@^1.0.8`
-- Existing QR and `NEELE` message-ID custom logic preserved
+- credential updates must be persisted
+- key updates must be persisted
+- ignoring key-store updates will eventually break message delivery
 
----
+## Socket configuration notes
+
+Useful socket options that remain especially relevant in this fork:
+
+| 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:
+
+```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
+
+```js
+await sock.sendMessage(jid, { text: 'hello' })
+```
+
+### Reply to a message
+
+```js
+await sock.sendMessage(
+  jid,
+  { text: 'this is a reply' },
+  { quoted: originalMessage }
+)
+```
+
+### Send an image
+
+```js
+await sock.sendMessage(jid, {
+  image: { url: './image.jpg' },
+  caption: 'sample'
+})
+```
+
+### Send a document
+
+```js
+await sock.sendMessage(jid, {
+  document: { url: './report.pdf' },
+  mimetype: 'application/pdf',
+  fileName: 'report.pdf'
+})
+```
+
+### Send a reaction
+
+```js
+await sock.sendMessage(jid, {
+  react: {
+    text: '❤',
+    key: message.key
+  }
+})
+```
+
+### Download received media
+
+```js
+const { downloadMediaMessage } = require('@neelegirl/baileys')
+
+const buffer = await downloadMediaMessage(
+  message,
+  'buffer',
+  {},
+  { logger: sock.logger, reuploadRequest: sock.updateMediaMessage }
+)
+```
+
+## Device and LID notes
+
+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
 
-This project is not affiliated with WhatsApp. Use responsibly and comply with platform terms and local laws.
+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