@neelegirl/wa-api 1.6.5 → 1.6.7

package/dist/Defaults/index.d.ts

@@ -8,11 +8,12 @@ export declare enum CALLBACK_KEY {
     ON_CONNECTED = "on-connected",
     ON_DISCONNECTED = "on-disconnected",
     ON_CONNECTING = "on-connecting",
-    ON_MESSAGE_UPDATED = "on-message-updated"
+    ON_MESSAGE_UPDATED = "on-message-updated",
+    ON_PAIRING_CODE = "on-pairing-code"
 }
 export declare abstract class Messages {
     static sessionAlreadyExist: (sessionId: string) => string;
     static sessionNotFound: (sessionId: string) => string;
     static paremetersRequired: (props: string[] | string) => string;
 }
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=index.d.ts.map

package/dist/Utils/index.d.ts

@@ -2,4 +2,5 @@ export * from "./phone-to-jid";
 export * from "./is-exist";
 export * from "./create-delay";
 export * from "./set-credentials-dir";
-//# sourceMappingURL=index.d.ts.map
+export * from "./set-credentials";
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@neelegirl/wa-api",
-  "version": "1.6.5",
-  "description": "Multi-session WhatsApp API wrapper built on @neelegirl/baileys",
+  "version": "1.6.7",
+  "description": "Multi-session WhatsApp wrapper built on top of @neelegirl/baileys",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": {
@@ -25,7 +25,7 @@
   "author": "Neele",
   "license": "MIT",
   "dependencies": {
-    "@neelegirl/baileys": "^2.1.5",
+    "@neelegirl/baileys": "^2.1.7",
     "pino": "^8.11.0"
   },
   "devDependencies": {
@@ -41,7 +41,7 @@
     "neelegirl"
   ],
   "peerDependencies": {
-    "@neelegirl/baileys": "^2.1.5"
+    "@neelegirl/baileys": "^2.1.7"
   },
   "engines": {
     "node": ">=20.0.0"

package/readme.md

@@ -1,222 +1,583 @@
-<div align="center">
+<div align="center">
 
 # @neelegirl/wa-api
 
-### High-level multi-session WhatsApp API on top of @neelegirl/baileys
+### Multi-session wrapper around `@neelegirl/baileys`
+### QR login, pairing code login, session management, and event hooks
 
-[![Version](https://img.shields.io/badge/Version-1.6.5-ff69b4?style=for-the-badge)](https://www.npmjs.com/package/@neelegirl/wa-api)
-[![Core](https://img.shields.io/badge/Core-@neelegirl%2Fbaileys%202.1.5-9b59b6?style=for-the-badge)](https://www.npmjs.com/package/@neelegirl/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/wa-api?style=for-the-badge&color=ff69b4&logo=npm)](https://www.npmjs.com/package/@neelegirl/wa-api)
+[![depends on](https://img.shields.io/badge/depends%20on-@neelegirl%2Fbaileys-9b59b6?style=for-the-badge)](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)
+
+---
 
 <p align="center">
-  <img src="https://files.catbox.moe/6np1ii.JPG" width="760" alt="Neelegirl wa-api Header" />
+  <img src="https://files.catbox.moe/6np1ii.JPG" width="760" alt="@neelegirl/wa-api" />
 </p>
 
-| Paket | Version | Abhaengigkeit |
+| Package | Version | Role |
 |---|---:|---|
-| `@neelegirl/wa-api` | `1.6.5` | `@neelegirl/baileys ^2.1.5` |
+| `@neelegirl/wa-api` | `1.6.7` | Convenience wrapper for session lifecycle and event-driven bot workflows |
 
-[Installation](#installation) · [Quickstart](#quickstart) · [Session-Logik](#session-logik) · [Messaging](#messaging)
+[Installation](#installation) · [Quickstart](#quickstart) · [API surface](#verified-api-surface) · [Events](#event-hooks) · [Storage](#session-storage) · [Release notes](#release-notes)
 
 </div>
 
 ---
 
-## Inhaltsverzeichnis
+## Table of Contents
 
-- [Uebersicht](#uebersicht)
+- [Overview](#overview)
+- [What this package is](#what-this-package-is)
+- [What this package is not](#what-this-package-is-not)
 - [Installation](#installation)
 - [Quickstart](#quickstart)
-- [Session-Logik](#session-logik)
-- [Messaging](#messaging)
-- [Event-System](#event-system)
-- [Aenderungen und Hinweise](#aenderungen--hinweise)
-- [libsignal Bezug](#libsignal-bezug)
-- [Word2Web Hinweise](#word2web-hinweise)
-- [Changelog](#changelog)
-- [Legal](#legal)
+- [Session lifecycle](#session-lifecycle)
+- [Message sending](#message-sending)
+- [Event hooks](#event-hooks)
+- [Session storage](#session-storage)
+- [Working with the underlying socket](#working-with-the-underlying-socket)
+- [Verified API surface](#verified-api-surface)
+- [Recent maintenance notes](#recent-maintenance-notes)
+- [Release notes](#release-notes)
+- [Disclaimer](#disclaimer)
 
----
+## Overview
 
-## Uebersicht
+`@neelegirl/wa-api` is a small wrapper package built on top of `@neelegirl/baileys`. Its job is to simplify:
 
-`@neelegirl/wa-api` ist die higher-level API fuer Multi-Session-Betrieb. Die eigentliche WhatsApp-Socket-Laufzeit kommt aus `@neelegirl/baileys`, wa-api kapselt darauf Sessionverwaltung, Callback-Flow und vereinfachtes Messaging.
+- starting sessions
+- reloading saved sessions
+- subscribing to high-level events
+- sending messages without wiring the socket boilerplate every time
 
-Aus den Quell-READMEs uebernommen und auf den echten Stand angepasst:
+It keeps the actual WhatsApp protocol handling inside the underlying Baileys fork.
 
-- Session-Start per QR oder Pairing-Code
-- Session-Laden aus Storage
-- Event-Hooks fuer Message/Connection/QR/Pairing
-- Helper fuer `sendMessage`, `sendStatusMentions`, `relayMessage`
-- technische Hinweise zu Reconnect, Credentials-Pfad und Update-Check
+## What this package is
 
----
+| Area | Purpose |
+|---|---|
+| session start helpers | launch QR or pairing-code sessions |
+| session lookup helpers | retrieve running sockets by session id |
+| event hooks | react to connection, QR, pairing, and message events |
+| message helpers | forward content into the underlying Baileys socket |
+| storage helpers | customize the credential folder name and suffix |
+
+## What this package is not
+
+- not a standalone REST API server
+- not a replacement for the full Baileys API surface
+- not a different transport layer
+- not a separate WhatsApp protocol implementation
+
+If you need deeper socket control, use `getSession(...)` and work directly with the returned Baileys socket.
 
 ## Installation
 
+Use npm:
+
 ```bash
 npm install @neelegirl/wa-api
 ```
 
-Import:
-
-```js
-// CommonJS
-const wa = require('@neelegirl/wa-api')
+Use yarn:
 
-// ESM (namespace import auf CJS)
-import * as wa from '@neelegirl/wa-api'
+```bash
+yarn add @neelegirl/wa-api
 ```
 
----
+Runtime requirement:
+
+```text
+Node.js >= 20
+```
 
 ## Quickstart
 
+### Start a session with QR
+
 ```js
 const wa = require('@neelegirl/wa-api')
 
-wa.onQRUpdated(({ sessionId, qr }) => {
-  console.log('QR for', sessionId)
-  console.log(qr)
-})
-
 wa.onConnected((sessionId) => {
-  console.log('Connected:', sessionId)
+  console.log('connected:', sessionId)
 })
 
 wa.onMessageReceived(async (msg) => {
-  const jid = msg.key?.remoteJid
-  const text = msg.message?.conversation || msg.message?.extendedTextMessage?.text || ''
-
-  if (jid && text.toLowerCase() === 'ping') {
-    await wa.sendMessage(msg.sessionId, jid, { text: 'pong' })
+  const text =
+    msg.message?.conversation ||
+    msg.message?.extendedTextMessage?.text ||
+    ''
+
+  if (text.toLowerCase() === 'ping') {
+    await wa.sendMessage(msg.sessionId, msg.key.remoteJid, {
+      text: 'pong'
+    })
   }
 })
 
-wa.startSession('main', { printQR: true }).catch(console.error)
+async function main() {
+  await wa.startSession('demo-session', { printQR: true })
+}
+
+main().catch(console.error)
 ```
 
----
+### Start a session with pairing code
+
+```js
+const wa = require('@neelegirl/wa-api')
 
-## Session-Logik
+wa.onPairingCode((sessionId, code) => {
+  console.log('pairing code for', sessionId, ':', code)
+})
 
-### Starten
+async function main() {
+  await wa.startSessionWithPairingCode(
+    'pairing-session',
+    { phoneNumber: '491234567890' }
+  )
+}
 
-- `startSession(sessionId, { printQR })`
-- `startSessionWithPairingCode(sessionId, { phoneNumber }, pairingCode?)`
+main().catch(console.error)
+```
 
-### Verwalten
+`startSessionWithPairingCode(...)` also accepts a third argument for a custom pairing-code string when your workflow needs one.
 
-- `getSession(sessionId)`
-- `getAllSession()`
-- `deleteSession(sessionId)`
-- `loadSessionsFromStorage()`
+## Session lifecycle
 
-### Laufzeitverhalten
+### Start a normal session
 
-- Credentials-Verzeichnisse: `wa_credentials/<session>_credentials`
-- Auto-Reconnect bis zu 10 Versuche (außer bei `loggedOut`)
-- npm-Update-Check fuer `@neelegirl/wa-api` einmal pro Prozess
+```js
+await wa.startSession('session-1', { printQR: true })
+```
 
----
+### Start with pairing code
 
-## Messaging
+```js
+await wa.startSessionWithPairingCode(
+  'session-2',
+  { phoneNumber: '491234567890' }
+)
+```
 
-### API
+### Load saved sessions from disk
 
-- `sendMessage(sessionId, jidOrPhone, content, options?)`
-- `sendStatusMentions(sessionId, content, options?)`
-- `relayMessage(sessionId, jidOrPhone, content, options?)`
+```js
+const loaded = await wa.loadSessionsFromStorage()
+console.log(loaded)
+```
 
-### Beispiele
+### Remove a session
 
 ```js
-// Text
-await wa.sendMessage('main', '491234567890', { text: 'Hallo' })
+await wa.deleteSession('session-1')
+```
 
-// Bild
-await wa.sendMessage('main', '491234567890@s.whatsapp.net', {
+### Get running sessions
+
+```js
+const one = wa.getSession('session-2')
+const allIds = wa.getAllSession()
+const allMap = wa.getAllSessionData()
+```
+
+## Message sending
+
+`sendMessage(...)` delegates to the Baileys socket of the chosen session.
+
+### Send text
+
+```js
+await wa.sendMessage('demo-session', '491234567890@s.whatsapp.net', {
+  text: 'hello'
+})
+```
+
+### Send image
+
+```js
+await wa.sendMessage('demo-session', '491234567890@s.whatsapp.net', {
   image: { url: './image.jpg' },
-  caption: 'Bild-Text'
+  caption: 'sample'
 })
+```
+
+### Send document
 
-// Antwort mit Quote
-await wa.sendMessage('main', '491234567890@s.whatsapp.net', {
-  text: 'Antwort'
-}, {
-  quoted: originalMessage
+```js
+await wa.sendMessage('demo-session', '491234567890@s.whatsapp.net', {
+  document: { url: './report.pdf' },
+  mimetype: 'application/pdf',
+  fileName: 'report.pdf'
 })
 ```
 
-Hinweis: Eingehende Nachrichten erhalten Helper wie `saveImage`, `saveVideo`, `saveDocument`.
+### React to a message
 
----
+```js
+await wa.sendMessage('demo-session', '491234567890@s.whatsapp.net', {
+  react: {
+    text: '❤',
+    key: message.key
+  }
+})
+```
 
-## Event-System
+### Relay an already prepared message payload
 
-- `onMessageReceived(listener)`
-- `onMessageUpdate(listener)`
-- `onQRUpdated(listener)`
-- `onConnected(listener)`
-- `onConnecting(listener)`
-- `onDisconnected(listener)`
-- `onPairingCode(listener)`
+```js
+await wa.relayMessage('demo-session', jid, content, options)
+```
 
-Beispiel:
+### Send a status mention payload
 
 ```js
+await wa.sendStatusMentions('demo-session', content, options)
+```
+
+## Event hooks
+
+The wrapper exposes high-level callbacks for the most common flows.
+
+### Connection events
+
+- `onConnected`
+- `onConnecting`
+- `onDisconnected`
+
+### QR and pairing
+
+- `onQRUpdated`
+- `onPairingCode`
+
+### Message events
+
+- `onMessageReceived`
+- `onMessageUpdate`
+
+### Example
+
+```js
+wa.onQRUpdated(({ sessionId, qr }) => {
+  console.log('qr updated for', sessionId)
+})
+
 wa.onMessageUpdate((sessionId, data) => {
-  console.log('Update in', sessionId, data.messageStatus)
+  console.log(sessionId, data.messageStatus)
 })
 ```
 
----
+## Session storage
 
-## Aenderungen & Hinweise
+Default storage values:
 
-Diese README uebernimmt die Erklaerungslogik aus den zwei Desktop-Quellen und bereinigt dabei veraltete oder widerspruechliche Punkte.
+| Setting | Default |
+|---|---|
+| credentials directory | `wa_credentials` |
+| credentials suffix | `_credentials` |
 
-Bewusst uebernommen:
+You can customize both before starting sessions:
 
-- Multi-Session-Nutzungslogik
-- Event- und Messaging-Erklaerungen
-- technische Hinweise zu Stability/Update/Session-Speicherung
+```js
+const wa = require('@neelegirl/wa-api')
 
-Bewusst nicht 1:1 uebernommen:
+wa.setCredentialsDir('./sessions')
+wa.setCredentials('_auth')
+```
 
-- veraltete Versionsangaben und alte Badge-Werte
-- Aussagen zu Features, die im lokalen Paket nicht eindeutig vorhanden sind
+## Working with the underlying socket
 
----
+When you need lower-level access, fetch the real Baileys socket:
 
-## libsignal Bezug
+```js
+const wa = require('@neelegirl/wa-api')
 
-wa-api nutzt libsignal nicht direkt als API, aber indirekt ueber `@neelegirl/baileys`. Der Krypto-/Session-Unterbau (Identity, PreKeys, SessionCipher) kommt damit aus `@neelegirl/libsignal`.
+async function main() {
+  await wa.startSession('demo-session', { printQR: true })
 
----
+  const sock = wa.getSession('demo-session')
+  if (sock) {
+    await sock.sendPresenceUpdate('unavailable')
+  }
+}
 
-## Word2Web Hinweise
+main().catch(console.error)
+```
 
-Kein dediziertes Word2Web-Modul im Paket. Word2Web-spezifische Hinweise sollten nur dokumentiert werden, wenn deine Host-App die entsprechende Logik bereitstellt.
+This is the intended path for advanced features that are not directly re-wrapped by `wa-api`.
 
----
+## Verified API surface
 
-## Changelog
+The following exports were verified in the currently prepared package:
 
-### 1.6.5
+### Session lifecycle
 
-- README inhaltlich aus den Quell-READMEs zusammengefuehrt und technisch bereinigt
-- Session-/Messaging-/Event-Doku auf echte `dist`-Exports abgestimmt
-- Abhaengigkeit und Peer-Range auf `@neelegirl/baileys ^2.1.5` aktualisiert
+- `startSession`
+- `startSessionWithPairingCode`
+- `startWhatsapp`
+- `deleteSession`
+- `loadSessionsFromStorage`
 
-### 1.6.4
+### Session lookup
 
-- Style-/Layout-Refresh der Dokumentation
-- API- und Paketmetadaten konsistent gemacht
+- `getSession`
+- `getAllSession`
+- `getAllSessionData`
 
----
+### Event hooks
+
+- `onMessageReceived`
+- `onMessageUpdate`
+- `onQRUpdated`
+- `onConnected`
+- `onConnecting`
+- `onDisconnected`
+- `onPairingCode`
+
+### Messaging
+
+- `sendMessage`
+- `relayMessage`
+- `sendStatusMentions`
+
+### Utilities
+
+- `phoneToJid`
+- `isExist`
+- `createDelay`
+- `setCredentialsDir`
+- `setCredentials`
+
+## Recent maintenance notes
+
+- the type surface now includes `ON_PAIRING_CODE` in `dist/Defaults/index.d.ts`
+- `setCredentials` is now reflected in `dist/Utils/index.d.ts`
+- the package depends on `@neelegirl/baileys@^2.1.7`
+- the README image was updated to the requested wa-api image
+
+## Wrapper design notes
+
+This package intentionally stays small.
+
+### Why
+
+The more logic gets duplicated here, the easier it becomes for the wrapper to drift away from the actual Baileys runtime below it.
+
+### Design rule
+
+`wa-api` should:
+
+- make common session flows easier
+- expose clear event hooks
+- keep message sending simple
+- hand you the real socket when you need deeper access
+
+It should not:
+
+- re-implement the entire Baileys protocol surface
+- invent a second independent event system
+- hide every low-level concern behind an artificial abstraction
+
+## More practical examples
+
+### Load stored sessions automatically on boot
+
+```js
+const wa = require('@neelegirl/wa-api')
+
+async function boot() {
+  const loaded = await wa.loadSessionsFromStorage()
+  console.log('loaded sessions:', loaded)
+}
+
+boot().catch(console.error)
+```
+
+### Start multiple sessions
+
+```js
+const wa = require('@neelegirl/wa-api')
+
+async function boot() {
+  await wa.startSession('alpha', { printQR: true })
+  await wa.startSession('beta', { printQR: true })
+}
+
+boot().catch(console.error)
+```
+
+### Send through a looked-up socket
+
+```js
+const wa = require('@neelegirl/wa-api')
+
+async function run() {
+  await wa.startSession('demo', { printQR: true })
+
+  const sock = wa.getSession('demo')
+  if (!sock) {
+    throw new Error('socket missing')
+  }
+
+  await sock.sendMessage('491234567890@s.whatsapp.net', {
+    text: 'sent through direct socket access'
+  })
+}
+
+run().catch(console.error)
+```
+
+### Use `phoneToJid`
+
+```js
+const wa = require('@neelegirl/wa-api')
+
+console.log(wa.phoneToJid({ to: '491234567890' }))
+console.log(wa.phoneToJid({ to: '12036304321-1612471065@g.us', isGroup: true }))
+```
+
+### Check if a target exists
+
+```js
+const wa = require('@neelegirl/wa-api')
+
+async function check() {
+  const exists = await wa.isExist({
+    sessionId: 'demo',
+    to: '491234567890'
+  })
+
+  console.log(exists)
+}
+
+check().catch(console.error)
+```
+
+### Delay helper
+
+```js
+const wa = require('@neelegirl/wa-api')
+
+async function example() {
+  await wa.createDelay(1000)
+  console.log('one second later')
+}
+```
+
+## Event behavior notes
+
+### `onMessageReceived`
+
+This is the most useful hook for bot logic.
+
+The message object carries:
+
+- session id
+- original Baileys message structure
+- convenience save helpers for image, video, and document
+
+### `onMessageUpdate`
+
+Use this when you want delivery-state style updates such as:
+
+- pending
+- server
+- delivered
+- read
+- played
+- error
+
+### `onQRUpdated`
+
+This is useful when you want to surface QR codes in:
+
+- a terminal
+- a panel
+- a web page
+- a bot-admin dashboard
+
+### `onPairingCode`
+
+Use this when a pairing-code flow is preferred over terminal QR scanning.
+
+## Realistic update notice
+
+This package already performs an npm registry update check once per process in its current runtime.
+
+### What that means
+
+- it can show a hint
+- it does not self-update
+- it does not rewrite your files
+- it only tells you a newer package version exists
+
+### How to actually update
+
+```bash
+npm install @neelegirl/wa-api@latest
+```
+
+or:
+
+```bash
+yarn add @neelegirl/wa-api@latest
+```
+
+### Why this is the realistic behavior
+
+A wrapper package should not silently change itself inside a running project. A clear update notice is realistic; automatic mutation of dependencies is not.
+
+## FAQ
+
+### Can I use wa-api without knowing Baileys?
+
+Yes, for common session and message flows. But for advanced control, understanding the underlying Baileys socket is still useful.
+
+### Is wa-api a web server?
+
+No.
+
+### Does wa-api keep sessions between runs?
+
+Yes, if you keep the credential directory and let it persist.
+
+### Does wa-api expose the raw socket?
+
+Yes, through `getSession(...)`.
+
+### Does it auto-update itself?
+
+No. It may show an update hint, but installation remains manual.
+
+### Is pairing code supported?
+
+Yes.
+
+### Is QR supported?
+
+Yes.
+
+## Release notes
+
+### 1.6.7
+
+- documentation expansion release
+- realistic update behavior note added
+- dependency metadata aligned to `@neelegirl/baileys@2.1.7`
+
+### 1.6.6
+
+- aligned dependency metadata with `@neelegirl/baileys@2.1.6`
+- fixed missing public type exposure for `ON_PAIRING_CODE`
+- fixed missing public type exposure for `setCredentials`
+- expanded and corrected package documentation
+
+### 1.6.5
+
+- previous local wrapper baseline before the current 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.