@neelegirl/wa-api 1.6.9 → 1.7.0

package/readme.md

@@ -1,611 +1,121 @@
-<div align="center">
-
 # @neelegirl/wa-api
 
-### Multi-session wrapper around `@neelegirl/baileys`
-### QR login, pairing code login, session management, and event hooks
-
-[![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" />
-</p>
-
-| Package | Version | Role |
-|---|---:|---|
-| `@neelegirl/wa-api` | `1.6.9` | Convenience wrapper for session lifecycle and event-driven bot workflows |
-
-[Installation](#installation) · [Quickstart](#quickstart) · [API surface](#verified-api-surface) · [Events](#event-hooks) · [Storage](#session-storage) · [Release notes](#release-notes)
-
-</div>
-
----
+![Neelegirl wa-api](https://files.catbox.moe/6np1ii.JPG)
 
-## Table of Contents
+Conservative multi-session WhatsApp wrapper around `@neelegirl/baileys`, kept compatible with the local Neelegirl runtime while cleaning obvious runtime and publish issues.
 
-- [Overview](#overview)
-- [Stack relationship](#stack-relationship)
-- [What this package is](#what-this-package-is)
-- [What this package is not](#what-this-package-is-not)
-- [Installation](#installation)
-- [Quickstart](#quickstart)
-- [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)
+## Package Status
 
-## Overview
+- Current package version: `1.7.0`
+- Intended companion package: `@neelegirl/baileys@^2.0.3`
+- Runtime format: CommonJS
 
-`@neelegirl/wa-api` is a small wrapper package built on top of `@neelegirl/baileys`. Its job is to simplify:
+This package is a wrapper layer. It is not a replacement for Baileys itself.
 
-- starting sessions
-- reloading saved sessions
-- subscribing to high-level events
-- sending messages without wiring the socket boilerplate every time
+## What Was Cleaned Up
 
-It keeps the actual WhatsApp protocol handling inside the underlying Baileys fork.
+- Fixed broken helper paths in `dist/Socket/index.js`
+- Fixed pairing callback registration
+- Fixed `loadSessionsFromStorage()` so it can run without undefined globals
+- Fixed `sendMessage()` and `relayMessage()` JID conversion paths
+- Removed the direct import side effect in `dist/whatsapp/index.js`
+- Aligned the `.d.ts` files with the exported runtime API
+- Rewrote the README to match the code that is actually present
 
-## Stack relationship
+## Main API
 
-`@neelegirl/wa-api` is intentionally the thin layer at the top of the local stack:
+Session management:
 
-| Package | Layer | Responsibility |
-|---|---|---|
-| `@neelegirl/libsignal` | crypto/session layer | session cipher state, identity keys, protocol primitives |
-| `@neelegirl/baileys` | WhatsApp Web runtime | socket, QR/pairing flow, device handling, events, media and message transport |
-| `@neelegirl/wa-api` | wrapper layer | multi-session lifecycle, convenience events, simplified send helpers |
+- `startSession(sessionId, options?)`
+- `startSessionWithPairingCode(sessionId, { phoneNumber }, customPairingCode?)`
+- `deleteSession(sessionId)`
+- `getAllSession()`
+- `getSession(sessionId)`
+- `getAllSessionData()`
+- `loadSessionsFromStorage()`
 
-The wrapper should stay small on purpose: it makes common flows easier without pretending to be a separate protocol implementation.
+Event registration:
 
-## What this package is
+- `onMessageReceived(listener)`
+- `onQRUpdated(listener)`
+- `onConnected(listener)`
+- `onDisconnected(listener)`
+- `onConnecting(listener)`
+- `onMessageUpdate(listener)`
+- `onPairingCode(listener)`
 
-| 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 |
+Messaging helpers:
 
-## What this package is not
+- `sendMessage(sessionId, jidOrPhone, content, options?)`
+- `relayMessage(sessionId, jidOrPhone, content, options?)`
+- `sendStatusMentions(sessionId, content, targets?)`
 
-- 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
+Utilities:
 
-If you need deeper socket control, use `getSession(...)` and work directly with the returned Baileys socket.
+- `phoneToJid({ to, isGroup? })`
+- `setCredentialsDir(dirname)`
+- `setCredentials(dirname)`
 
 ## 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.onConnected((sessionId) => {
-  console.log('connected:', sessionId)
-})
-
-wa.onMessageReceived(async (msg) => {
-  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
-
-```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
-
-```js
-await wa.relayMessage('demo-session', jid, content, options)
-```
-
-### 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(sessionId, data.messageStatus)
-})
-```
-
-## Session storage
-
-Default storage values:
-
-| Setting | Default |
-|---|---|
-| credentials directory | `wa_credentials` |
-| credentials suffix | `_credentials` |
-
-You can customize both before starting sessions:
-
-```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:
+## Quick Start
 
 ```js
-const wa = require('@neelegirl/wa-api')
+const onimai = 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 README was rechecked on `2026-03-20` against the local source wrapper and the target runtime package
-- descriptions were kept aligned with the actual wrapper role instead of repeating full Baileys runtime claims
-- 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 now tracks `@neelegirl/baileys@^2.1.9`
-- the README was kept aligned with the actual wrapper surface instead of promising Baileys internals that belong only to the lower runtime package
-- 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:
+  await onimai.startSession('demo-session', { printQR: true })
 
-- 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'
+  onimai.onConnected((sessionId) => {
+    console.log(`connected: ${sessionId}`)
   })
-}
-
-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')
+  onimai.onMessageReceived(async (msg) => {
+    const text =
+      msg.message?.conversation ||
+      msg.message?.extendedTextMessage?.text ||
+      ''
 
-async function check() {
-  const exists = await wa.isExist({
-    sessionId: 'demo',
-    to: '491234567890'
+    if (text.toLowerCase() === 'ping') {
+      await onimai.sendMessage(msg.sessionId, msg.key.remoteJid, { text: 'pong' })
+    }
   })
-
-  console.log(exists)
 }
 
-check().catch(console.error)
+main().catch(console.error)
 ```
 
-### Delay helper
+## Pairing Code Example
 
 ```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
+const onimai = require('@neelegirl/wa-api')
 
-### `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:
+onimai.onPairingCode((sessionId, code) => {
+  console.log(`pairing code for ${sessionId}: ${code}`)
+})
 
-```bash
-yarn add @neelegirl/wa-api@latest
+onimai.startSessionWithPairingCode(
+  'pairing-session',
+  { phoneNumber: '491234567890' },
+  'ONIMAIII'
+).catch(console.error)
 ```
 
-### 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.9
-
-- dependency metadata aligned to `@neelegirl/baileys@2.1.9`
-- documentation refreshed after the hosted LID/session migration stabilization in the underlying runtime
-- public wrapper guidance rechecked against the current `dist` surface on `2026-03-20`
-
-### 1.6.8
-
-- patch release aligned to `@neelegirl/baileys@2.1.8`
-- documentation refreshed so the wrapper release line matches the currently published stack
-- no fake auto-update behavior added; runtime update hints remain informational only
-
-### 1.6.7
-
-- documentation expansion release
-- realistic update behavior note added
-- dependency metadata aligned to `@neelegirl/baileys@2.1.7`
-
-### 1.6.6
+## Notes
 
-- 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
+- This wrapper depends on the current local behavior of `@neelegirl/baileys`
+- QR handling and reconnect behavior stay in the socket layer, not in the messaging helper
+- `dist/whatsapp/index.js` is a legacy internal file and is not the primary public entrypoint
 
-### 1.6.5
+## Requirements
 
-- previous local wrapper baseline before the current maintenance pass
+- Node.js `>=16.0.0`
+- `@neelegirl/baileys@^2.0.3`
 
-## Disclaimer
+## License
 
-This project is not affiliated with WhatsApp. Use it responsibly. Do not use it for spam, stalking, or abusive automation.
+ISC