@neelegirl/wa-api 1.6.6 → 1.6.8

package/package.json

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

package/readme.md

@@ -18,7 +18,7 @@
 
 | Package | Version | Role |
 |---|---:|---|
-| `@neelegirl/wa-api` | `1.6.6` | Convenience wrapper for session lifecycle and event-driven bot workflows |
+| `@neelegirl/wa-api` | `1.6.8` | 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)
 
@@ -354,11 +354,225 @@ The following exports were verified in the currently prepared package:
 
 - 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 package depends on `@neelegirl/baileys@^2.1.8`
 - 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.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
 
 - aligned dependency metadata with `@neelegirl/baileys@2.1.6`