@neelegirl/wa-api 1.5.1 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +32 -10
  2. package/readme.md +99 -179
package/package.json CHANGED
@@ -1,36 +1,58 @@
1
1
  {
2
2
  "name": "@neelegirl/wa-api",
3
- "version": "1.5.1",
4
- "description": "Multi Session Whatsapp Library",
3
+ "version": "1.6.0",
4
+ "description": "Multi-session WhatsApp wrapper built on @neelegirl/baileys for QR, pairing and message automation.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
+ "exports": {
8
+ ".": {
9
+ "types": "./dist/index.d.ts",
10
+ "require": "./dist/index.js",
11
+ "default": "./dist/index.js"
12
+ },
13
+ "./package.json": "./package.json"
14
+ },
7
15
  "repository": {
8
16
  "type": "git",
9
17
  "url": "git+https://github.com/neelegirly/neelegirl-wa-api.git"
10
18
  },
11
19
  "homepage": "https://github.com/neelegirly/neelegirl-wa-api#readme",
12
20
  "bugs": {
13
- "url": "https://github.com/neelegirly/neelegirl-wa-api"
21
+ "url": "https://github.com/neelegirly/neelegirl-wa-api/issues"
14
22
  },
15
- "files": ["dist/**/*"],
23
+ "keywords": [
24
+ "whatsapp",
25
+ "wa-api",
26
+ "multi-session",
27
+ "pairing",
28
+ "qr",
29
+ "automation",
30
+ "neelegirl"
31
+ ],
32
+ "files": [
33
+ "dist/**/*",
34
+ "readme.md",
35
+ "LICENSE"
36
+ ],
16
37
  "scripts": {
17
- "build": "tsc",
18
- "start": "tsc && node ./dist/index.js",
19
- "test": "echo \"Error: no test specified\" && exit 1",
38
+ "start": "node ./dist/index.js",
20
39
  "run-script": "node ./dist/index.js"
21
40
  },
22
- "author": { "name": "Neele" },
41
+ "author": "Neele",
23
42
  "license": "ISC",
24
43
  "dependencies": {
25
- "jest": "^29.0.0",
26
44
  "@adiwajshing/keyed-db": "^0.2.4",
27
45
  "@hapi/boom": "^10.0.1",
28
- "@neelegirl/baileys": "^2.0.5",
46
+ "@neelegirl/baileys": "^2.1.0",
47
+ "jest": "^29.0.0",
29
48
  "mime": "^3.0.0",
30
49
  "pino": "^8.11.0",
31
50
  "qrcode-terminal": "^0.12.0"
32
51
  },
33
52
  "devDependencies": {
34
53
  "@types/mime": "^3.0.1"
54
+ },
55
+ "engines": {
56
+ "node": ">=20.0.0"
35
57
  }
36
58
  }
package/readme.md CHANGED
@@ -1,243 +1,163 @@
1
1
  <div align="center">
2
2
 
3
- # 💌 @neelegirl/wa-api 💌
3
+ # @neelegirl/wa-api
4
4
 
5
- ### *Multi-Session WhatsApp – einfach & stabil*
6
- ### *QR · Pairing · Auto-Reconnect · Smart Queue Ready*
5
+ **Mehrfach-Sessions, QR-Login, Pairing-Code und vereinfachtes Messaging**
6
+ **aufbauend auf dem gepflegten `@neelegirl/baileys`-Fork.**
7
7
 
8
- [![Version](https://img.shields.io/badge/Version-1.5.1-ff69b4?style=for-the-badge&logo=github)](https://github.com/neelegirl/wa-api)
9
- [![Baileys](https://img.shields.io/badge/@neelegirl/baileys-2.0.4-9b59b6?style=for-the-badge)](https://www.npmjs.com/package/@neelegirl/baileys)
10
- [![Baileys API](https://img.shields.io/badge/Baileys_API-1.7.2-9b59b6?style=for-the-badge)](https://github.com/WhiskeySockets/Baileys)
11
8
  [![npm](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)
12
- [![Downloads](https://img.shields.io/npm/dw/@neelegirl/wa-api?style=for-the-badge&color=ff69b4&logo=npm)](https://www.npmjs.com/package/@neelegirl/wa-api)
13
- [![License](https://img.shields.io/github/license/neelegirl/wa-api?style=for-the-badge&color=ff69b4)](LICENSE)
14
-
15
- ---
9
+ [![Dependency](https://img.shields.io/badge/@neelegirl%2Fbaileys-2.1.x-6f42c1?style=for-the-badge)](https://www.npmjs.com/package/@neelegirl/baileys)
10
+ [![Node](https://img.shields.io/badge/Node-20+-2ea043?style=for-the-badge&logo=node.js)](https://nodejs.org)
16
11
 
17
12
  <p align="center">
18
- <img src="https://files.catbox.moe/63h8xn.jpeg" width="720" alt="Neele WA-API Header" />
13
+ <img src="https://files.catbox.moe/6np1ii.JPG" width="920" alt="Neelegirl wa-api Hero" />
19
14
  </p>
20
15
 
21
- | 📦 Paket | 🎯 Baileys | ✨ Highlights |
22
- |----------|------------|----------------|
23
- | **@neelegirl/wa-api v1.5.1** | **@neelegirl/baileys 2.0.5** | Multi-Session · QR · Pairing · Update-Check von npm |
24
-
25
- **✨ v1.5.1** · README Glow-Up · Kompatibel mit **@neelegirl/baileys 2.0.5** & **Baileys API 1.7.2** · Update-Prüfung via npm-Registry
26
-
27
- [**Installation**](#-installation) · [**Quickstart**](#-quickstart-guide) · [**Features**](#-features) · [**API**](#-vollständige-api-referenz) · [**Support**](#-support--community)
28
-
29
16
  </div>
30
17
 
31
- ---
32
-
33
- ## 📋 Inhaltsverzeichnis
34
-
35
- - [✨ Was ist @neelegirl/wa-api?](#-was-ist-neelegirlwa-api)
36
- - [🚀 Installation](#-installation)
37
- - [📖 Quickstart Guide](#-quickstart-guide)
38
- - [✨ Features](#-features)
39
- - [📲 Session Management](#-session-management)
40
- - [💬 Nachrichten senden](#-nachrichten-senden)
41
- - [🎧 Event Listener](#-event-listener)
42
- - [🔧 Erweiterte Funktionen](#-erweiterte-funktionen)
43
- - [📚 Vollständige API-Referenz](#-vollständige-api-referenz)
44
- - [⚠️ Wichtige Hinweise](#️-wichtige-hinweise)
45
- - [💬 Support & Community](#-support--community)
46
-
47
- ---
48
-
49
- ## ✨ Was ist @neelegirl/wa-api?
50
-
51
- <div align="center">
52
-
53
- ### 🎯 **Die perfekte Lösung für Multi-Session WhatsApp Bots** 🎯
54
-
55
- </div>
18
+ ## Überblick
56
19
 
57
- | Feature | Beschreibung | Status |
58
- |---------|-------------|--------|
59
- | 🔀 **Multi-Session** | Mehrere WhatsApp-Sessions gleichzeitig | ✅ |
60
- | 💎 **Universal API** | Einfache `sendMessage` für alle Typen | ✅ |
61
- | ⚡ **RelayMessage** | Direkte Nachrichten-Weiterleitung | ✅ |
62
- | 🔄 **Auto-Reconnect** | Automatisches Wiederverbinden | ✅ |
63
- | 📱 **QR-Code** | Schöne QR-Code-Anzeige | ✅ |
64
- | 🔔 **Auto-Updates** | Automatische Update-Prüfung (nur einmal) | ✅ |
65
- | 🧩 **LID-Support** | Vollständige LID-Kompatibilität | ✅ |
66
- | 🎨 **Einfach** | Simple API für Anfänger | ✅ |
67
- | 🚀 **Smart Queue** | Nutzt Baileys Smart Message Queue | ✅ |
20
+ `@neelegirl/wa-api` ist die bequemere Multi-Session-Schicht für Projekte, die nicht direkt auf der vollständigen Baileys-Oberfläche arbeiten wollen. Das Paket nutzt `@neelegirl/baileys` als eigentliche WhatsApp-Web-Basis und stellt darauf ein kompakteres API-Set für Sessions, Event-Hooks und das Senden von Nachrichten bereit.
68
21
 
69
- > ⚠️ **Wichtig**: Diese Library funktioniert **ausschließlich** mit **@neelegirl/baileys** (empfohlen **v2.0.4**, Baileys API **1.7.2**)!
22
+ ## Update-Stand
70
23
 
71
- ---
24
+ - abgestimmt auf `@neelegirl/baileys@2.1.x`
25
+ - Dokumentation auf den realen Dist-Exports bereinigt
26
+ - Bild/Branding modernisiert
27
+ - Hinweise ergänzt, was lokal funktioniert und was bewusst nicht behauptet wird
72
28
 
73
- ## 🚀 Installation
29
+ **Wichtig:** `wa-api` baut auf dem aktualisierten Neelegirl-Baileys-Fork auf. Es ist keine eigenständige Neuimplementierung von WhiskeySockets/Baileys, sondern eine Wrapper-Schicht darüber.
74
30
 
75
- ### 📦 Mit npm
31
+ ## Installation
76
32
 
77
33
  ```bash
78
- npm install @neelegirl/wa-api@latest
34
+ npm install @neelegirl/wa-api @neelegirl/baileys
79
35
  ```
80
36
 
81
- ### 📦 Mit yarn
37
+ oder:
82
38
 
83
39
  ```bash
84
- yarn add @neelegirl/wa-api@latest
40
+ yarn add @neelegirl/wa-api @neelegirl/baileys
85
41
  ```
86
42
 
87
- ### 📥 Import
88
-
89
- ```javascript
90
- // CommonJS
91
- const onimai = require('@neelegirl/wa-api');
92
-
93
- // ES Module
94
- import * as onimai from '@neelegirl/wa-api';
95
- ```
43
+ ## Voraussetzungen
96
44
 
97
- ---
45
+ - Node.js `20+`
46
+ - WhatsApp Multi-Device-Konto
47
+ - persistenter Speicherort für Sessiondaten
98
48
 
99
- ## 📖 Quickstart Guide
49
+ ## Schnellstart
100
50
 
101
- ### 🎯 **Für Anfänger: Dein erster Multi-Session Bot**
51
+ ```js
52
+ const wa = require('@neelegirl/wa-api')
102
53
 
103
- ```javascript
104
- const onimai = require('@neelegirl/wa-api');
54
+ async function bootstrap() {
55
+ await wa.startSession('main-session', {
56
+ printQR: true
57
+ })
105
58
 
106
- // 1️⃣ Session starten (mit QR-Code)
107
- async function start() {
108
- // Session starten
109
- await onimai.startSession('meine-session', {
110
- printQR: true // QR-Code anzeigen
111
- });
112
-
113
- console.log('✅ Session gestartet!');
59
+ console.log('Session gestartet')
114
60
  }
115
61
 
116
- // 2️⃣ Nachrichten empfangen
117
- onimai.onMessageReceived(async (msg) => {
118
- const { sessionId, key, message } = msg;
119
- const from = key.remoteJid;
120
- const text = message?.conversation || message?.extendedTextMessage?.text || '';
121
-
122
- // Echo-Bot
123
- if (text.toLowerCase() === 'hallo') {
124
- await onimai.sendMessage(sessionId, from, {
125
- text: '🌸 Hallo! Ich bin ein Onimai-Bot! ✨'
126
- });
127
- }
128
- });
62
+ wa.onConnected((sessionId) => {
63
+ console.log(`[${sessionId}] verbunden`)
64
+ })
129
65
 
130
- // 3️⃣ Verbindungs-Status
131
- onimai.onConnected((sessionId) => {
132
- console.log(`✅ Session ${sessionId} ist verbunden!`);
133
- });
66
+ wa.onDisconnected((sessionId) => {
67
+ console.log(`[${sessionId}] getrennt`)
68
+ })
134
69
 
135
- onimai.onDisconnected((sessionId) => {
136
- console.log(`❌ Session ${sessionId} wurde getrennt`);
137
- });
70
+ wa.onMessageReceived(async ({ sessionId, key, message }) => {
71
+ const jid = key.remoteJid
72
+ const text = message?.conversation || message?.extendedTextMessage?.text || ''
138
73
 
139
- // Bot starten
140
- start().catch(console.error);
141
- ```
74
+ if (text.toLowerCase() === 'ping') {
75
+ await wa.sendMessage(sessionId, jid, { text: 'pong' })
76
+ }
77
+ })
142
78
 
143
- ### 🎨 **Was passiert hier?**
79
+ bootstrap().catch(console.error)
80
+ ```
144
81
 
145
- 1. **`startSession`**: Startet eine neue WhatsApp-Session mit QR-Code
146
- 2. **`onMessageReceived`**: Event-Handler für neue Nachrichten
147
- 3. **`sendMessage`**: Sendet Nachrichten an einen Chat
148
- 4. **`onConnected`/`onDisconnected`**: Events für Verbindungsstatus
82
+ ## Session-API
149
83
 
150
- ---
84
+ ### Starten
151
85
 
152
- ## ✨ Features
86
+ ```js
87
+ await wa.startSession('session-a', { printQR: true })
153
88
 
154
- ### 🔥 **Hauptfeatures**
89
+ await wa.startSessionWithPairingCode('session-b', {
90
+ phoneNumber: '491234567890'
91
+ })
92
+ ```
155
93
 
156
- - ✅ **Multi-Session Support** - Mehrere Sessions gleichzeitig verwalten
157
- - ✅ **Universal sendMessage** - Einfache API für alle Nachrichtentypen
158
- - ✅ **Auto-Reconnect** - Automatisches Wiederverbinden bei Verbindungsabbruch
159
- - ✅ **QR-Code Display** - Schöne QR-Code-Anzeige im Terminal
160
- - ✅ **Auto-Update-Check** - Automatische Prüfung auf neue Versionen (nur einmal pro Prozess)
161
- - ✅ **LID-Kompatibel** - Vollständige Linked ID Unterstützung
162
- - ✅ **Session-Management** - Einfaches Starten, Stoppen und Verwalten
163
- - ✅ **Event-System** - Umfangreiches Event-System für alle Events
164
- - ✅ **Smart Queue Ready** - Kompatibel mit Baileys Smart Message Queue
94
+ ### Verwalten
165
95
 
166
- ---
96
+ ```js
97
+ const all = wa.getAllSession()
98
+ const one = wa.getSession('session-a')
167
99
 
168
- ## 📲 Session Management
100
+ await wa.deleteSession('session-a')
101
+ await wa.loadSessionsFromStorage()
102
+ ```
169
103
 
170
- ### 🚀 **Session starten**
104
+ ## Messaging
171
105
 
172
- ```javascript
173
- // Mit QR-Code (Standard)
174
- await onimai.startSession('session1', {
175
- printQR: true // QR-Code im Terminal anzeigen
176
- });
106
+ Die Dist-API bietet einen universellen `sendMessage`-Wrapper über die aktive Session:
177
107
 
178
- // Mit Pairing-Code (ohne QR-Code)
179
- await onimai.startSessionWithPairingCode('session2', {
180
- phoneNumber: '491234567890' // Ohne +, mit Ländercode
181
- });
108
+ ```js
109
+ await wa.sendMessage('session-a', '491234567890@s.whatsapp.net', {
110
+ text: 'Hallo aus wa-api'
111
+ })
182
112
  ```
183
113
 
184
- ### 📋 **Sessions verwalten**
185
-
186
- ```javascript
187
- // Alle Sessions auflisten
188
- const allSessions = onimai.getAllSession();
189
- console.log('Aktive Sessions:', allSessions);
190
- // Output: ['session1', 'session2', 'session3']
114
+ Zusätzlich gibt es `relayMessage`, wenn du gezielt weiterleiten bzw. rohe Baileys-Pfade der Session nutzen willst.
191
115
 
192
- // Eine Session abrufen
193
- const session = onimai.getSession('session1');
194
- if (session) {
195
- console.log('Session gefunden!');
196
- }
116
+ ## Event-Hooks
197
117
 
198
- // Session löschen
199
- await onimai.deleteSession('session1');
200
- ```
118
+ Vorhandene Event-Helper im Dist-Build:
201
119
 
202
- ### 💾 **Sessions aus Storage laden**
120
+ - `onMessageReceived(listener)`
121
+ - `onQRUpdated(listener)`
122
+ - `onConnected(listener)`
123
+ - `onDisconnected(listener)`
124
+ - `onConnecting(listener)`
125
+ - `onMessageUpdate(listener)`
126
+ - `onPairingCode(listener)`
203
127
 
204
- ```javascript
205
- // Alle gespeicherten Sessions automatisch laden
206
- const loadedSessions = await onimai.loadSessionsFromStorage();
207
- console.log('Geladene Sessions:', loadedSessions);
208
- // Output: ['session1', 'session2']
209
- ```
128
+ ## Konsole beim Start
210
129
 
211
- ---
130
+ Diese Zustände sind beim echten Start normal:
212
131
 
213
- ## 💬 Nachrichten senden
132
+ - QR wird im Terminal angezeigt, wenn noch keine Session gespeichert ist
133
+ - Pairing-Code wird ausgegeben, wenn du die Pairing-Variante nutzt
134
+ - `connected`/`disconnected` wechseln bei Reconnects sauber
135
+ - nach `creds.update` bleibt die Session für Folgestarts erhalten
214
136
 
215
- ### 📨 **Grundlegende Verwendung**
137
+ ## Was wirklich funktioniert
216
138
 
217
- ```javascript
218
- await onimai.sendMessage(sessionId, jidOrPhone, content, options);
219
- ```
139
+ - mehrere parallele Sessions
140
+ - Sessionstart per QR
141
+ - Sessionstart per Pairing-Code
142
+ - Nachrichtenversand über aktive Sessions
143
+ - Sessionzugriff über `getSession()` für tiefergehende eigene Arbeit
144
+ - Event-Listener für eingehende Nachrichten und Verbindungsstatus
220
145
 
221
- **Parameter:**
222
- - `sessionId` - Die Session-ID (z.B. 'session1')
223
- - `jidOrPhone` - WhatsApp-ID oder Telefonnummer (z.B. '491234567890@s.whatsapp.net' oder '491234567890')
224
- - `content` - Der Nachrichteninhalt (siehe Beispiele unten)
225
- - `options` - Optionale Parameter (z.B. `{ quoted: message }`)
146
+ ## Was bewusst **nicht** behauptet wird
226
147
 
227
- ### 📝 **Nachrichtentypen**
148
+ - kein separater, vollständig dokumentierter Source-Build im Paket selbst
149
+ - kein vollständiger Ersatz für das volle Baileys-API-Surface
150
+ - kein Anspruch auf vollständigen Upstream-Gleichstand in jeder internen Implementierungsdetailschicht
228
151
 
229
- #### 1. **Text-Nachricht**
152
+ ## Empfehlung für produktive Nutzung
230
153
 
231
- ```javascript
232
- await onimai.sendMessage('session1', '491234567890@s.whatsapp.net', {
233
- text: 'Hallo! 🌸'
234
- });
235
- ```
154
+ - `@neelegirl/baileys` und `@neelegirl/wa-api` immer gemeinsam aktualisieren
155
+ - Sessionordner außerhalb flüchtiger Deploy-Ordner speichern
156
+ - bei Multi-Session-Projekten eigene Health-/Reconnect-Logs ergänzen
236
157
 
237
- #### 2. **Bild mit Caption**
158
+ ## Lizenz
238
159
 
239
- ```javascript
240
- await onimai.sendMessage('session1', '491234567890@s.whatsapp.net', {
160
+ `wa-api` bleibt die einfache Bedienebene. Die technische WhatsApp-Web-Basis stammt aus `@neelegirl/baileys`, das selektiv auf aktuellem WhiskeySockets/Baileys-Wissen aufsetzt.
241
161
  image: { url: './bild.jpg' },
242
162
  caption: 'Schönes Bild! ✨'
243
163
  });