@neelegirl/wa-api 1.6.4 → 1.6.6

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/Socket/index.js

@@ -16,7 +16,7 @@ const sessions = new Map();
 const callback = new Map();
 const retryCount = new Map();
 
-let CURRENT_WA_API_VERSION = "1.5.1";
+let CURRENT_WA_API_VERSION = "1.6.5";
 let waApiUpdateCheckDone = false;
 
 try {

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.4",
-  "description": "Multi-session WhatsApp API wrapper built on @neelegirl/baileys",
+  "version": "1.6.6",
+  "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.4",
+    "@neelegirl/baileys": "^2.1.6",
     "pino": "^8.11.0"
   },
   "devDependencies": {
@@ -41,9 +41,9 @@
     "neelegirl"
   ],
   "peerDependencies": {
-    "@neelegirl/baileys": "^2.1.4"
+    "@neelegirl/baileys": "^2.1.6"
   },
   "engines": {
     "node": ">=20.0.0"
   }
-}
+}

package/readme.md

@@ -1,23 +1,26 @@
-<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.4-ff69b4?style=for-the-badge)](https://www.npmjs.com/package/@neelegirl/wa-api)
-[![Core](https://img.shields.io/badge/Core-@neelegirl%2Fbaileys%202.1.4-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>
 
-| Package | Latest Version | Depends On |
+| Package | Version | Role |
 |---|---:|---|
-| `@neelegirl/wa-api` | `1.6.4` | `@neelegirl/baileys ^2.1.4` |
+| `@neelegirl/wa-api` | `1.6.6` | Convenience wrapper for session lifecycle and event-driven bot workflows |
 
-[Installation](#installation) · [Quickstart](#quickstart) · [API Overview](#api-overview) · [Operational Notes](#operational-notes)
+[Installation](#installation) · [Quickstart](#quickstart) · [API surface](#verified-api-surface) · [Events](#event-hooks) · [Storage](#session-storage) · [Release notes](#release-notes)
 
 </div>
 
@@ -26,120 +29,347 @@
 ## Table of Contents
 
 - [Overview](#overview)
+- [What this package is](#what-this-package-is)
+- [What this package is not](#what-this-package-is-not)
 - [Installation](#installation)
 - [Quickstart](#quickstart)
-- [API Overview](#api-overview)
-- [Operational Notes](#operational-notes)
-- [Word2Web Notes](#word2web-notes)
-- [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
 
-`@neelegirl/wa-api` provides a higher-level interface for multi-session WhatsApp automation while delegating socket/runtime behavior to `@neelegirl/baileys`.
+`@neelegirl/wa-api` is a small wrapper package built on top of `@neelegirl/baileys`. Its job is to simplify:
 
-Main capabilities:
+- starting sessions
+- reloading saved sessions
+- subscribing to high-level events
+- sending messages without wiring the socket boilerplate every time
 
-- Session lifecycle management (`start`, `stop`, `delete`, `load`)
-- QR callback flow and pairing-code callback flow
-- Message receive/update callbacks
-- Helper senders (`sendMessage`, `sendStatusMentions`, `relayMessage`)
-- File-based credential persistence per session
+It keeps the actual WhatsApp protocol handling inside the underlying Baileys fork.
 
----
+## 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
 ```
 
----
+Use yarn:
+
+```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 updated:', 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 || ''
+  const text =
+    msg.message?.conversation ||
+    msg.message?.extendedTextMessage?.text ||
+    ''
+
+  if (text.toLowerCase() === 'ping') {
+    await wa.sendMessage(msg.sessionId, msg.key.remoteJid, {
+      text: 'pong'
+    })
+  }
+})
+
+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')
+
+wa.onPairingCode((sessionId, code) => {
+  console.log('pairing code for', sessionId, ':', code)
+})
+
+async function main() {
+  await wa.startSessionWithPairingCode(
+    'pairing-session',
+    { phoneNumber: '491234567890' }
+  )
+}
+
+main().catch(console.error)
+```
+
+`startSessionWithPairingCode(...)` also accepts a third argument for a custom pairing-code string when your workflow needs one.
+
+## Session lifecycle
+
+### Start a normal session
+
+```js
+await wa.startSession('session-1', { printQR: true })
+```
+
+### Start with pairing code
+
+```js
+await wa.startSessionWithPairingCode(
+  'session-2',
+  { phoneNumber: '491234567890' }
+)
+```
+
+### Load saved sessions from disk
+
+```js
+const loaded = await wa.loadSessionsFromStorage()
+console.log(loaded)
+```
+
+### Remove a session
+
+```js
+await wa.deleteSession('session-1')
+```
+
+### 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: 'sample'
+})
+```
+
+### Send document
 
-  if (jid && text.toLowerCase() === 'ping') {
-    await wa.sendMessage(msg.sessionId, jid, { text: 'pong' })
+```js
+await wa.sendMessage('demo-session', '491234567890@s.whatsapp.net', {
+  document: { url: './report.pdf' },
+  mimetype: 'application/pdf',
+  fileName: 'report.pdf'
+})
+```
+
+### React to a message
+
+```js
+await wa.sendMessage('demo-session', '491234567890@s.whatsapp.net', {
+  react: {
+    text: '❤',
+    key: message.key
   }
 })
+```
+
+### Relay an already prepared message payload
 
-wa.startSession('main', { printQR: true }).catch(console.error)
+```js
+await wa.relayMessage('demo-session', jid, content, options)
 ```
 
----
+### Send a status mention payload
 
-## API Overview
+```js
+await wa.sendStatusMentions('demo-session', content, options)
+```
 
-Session lifecycle:
+## Event hooks
 
-- `startSession(sessionId, options)`
-- `startSessionWithPairingCode(sessionId, { phoneNumber }, pairingCode?)`
-- `deleteSession(sessionId)`
-- `getSession(sessionId)`
-- `getAllSession()`
-- `loadSessionsFromStorage()`
+The wrapper exposes high-level callbacks for the most common flows.
 
-Messaging:
+### Connection events
 
-- `sendMessage(sessionId, jidOrPhone, content, options?)`
-- `sendStatusMentions(sessionId, content, options?)`
-- `relayMessage(sessionId, jidOrPhone, content, options?)`
+- `onConnected`
+- `onConnecting`
+- `onDisconnected`
 
-Event hooks:
+### QR and pairing
 
-- `onMessageReceived(listener)`
-- `onMessageUpdate(listener)`
-- `onQRUpdated(listener)`
-- `onConnected(listener)`
-- `onConnecting(listener)`
-- `onDisconnected(listener)`
-- `onPairingCode(listener)`
+- `onQRUpdated`
+- `onPairingCode`
 
----
+### Message events
 
-## Operational Notes
+- `onMessageReceived`
+- `onMessageUpdate`
 
-- Node.js `>=20` required
-- Credentials default path: `wa_credentials/<session>_credentials`
-- Reconnect retries are handled internally
-- Depends on `@neelegirl/baileys` runtime behavior, including custom Neelegirl compatibility logic
+### Example
 
----
+```js
+wa.onQRUpdated(({ sessionId, qr }) => {
+  console.log('qr updated for', sessionId)
+})
 
-## Word2Web Notes
+wa.onMessageUpdate((sessionId, data) => {
+  console.log(sessionId, data.messageStatus)
+})
+```
 
-No dedicated Word2Web module is bundled in this package. Only document Word2Web behavior if implemented by your own host app.
+## Session storage
 
----
+Default storage values:
 
-## Changelog
+| Setting | Default |
+|---|---|
+| credentials directory | `wa_credentials` |
+| credentials suffix | `_credentials` |
 
-### 1.6.4
+You can customize both before starting sessions:
 
-- README restyled to match the main project presentation style
-- Package metadata aligned with current dependency versions
-- Dependency/peer range updated to `@neelegirl/baileys ^2.1.4`
+```js
+const wa = require('@neelegirl/wa-api')
 
----
+wa.setCredentialsDir('./sessions')
+wa.setCredentials('_auth')
+```
+
+## Working with the underlying socket
+
+When you need lower-level access, fetch the real Baileys socket:
+
+```js
+const wa = require('@neelegirl/wa-api')
+
+async function main() {
+  await wa.startSession('demo-session', { printQR: true })
+
+  const sock = wa.getSession('demo-session')
+  if (sock) {
+    await sock.sendPresenceUpdate('unavailable')
+  }
+}
+
+main().catch(console.error)
+```
+
+This is the intended path for advanced features that are not directly re-wrapped by `wa-api`.
+
+## Verified API surface
+
+The following exports were verified in the currently prepared package:
+
+### Session lifecycle
+
+- `startSession`
+- `startSessionWithPairingCode`
+- `startWhatsapp`
+- `deleteSession`
+- `loadSessionsFromStorage`
+
+### Session lookup
+
+- `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.6`
+- the README image was updated to the requested wa-api image
+
+## Release notes
+
+### 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
 
-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.