@deathnaitsa/wa-api 1.0.13 → 1.0.14

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 +1 -1
  2. package/readme.md +82 -116
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deathnaitsa/wa-api",
3
- "version": "1.0.13",
3
+ "version": "1.0.14",
4
4
  "description": "Multi Session Whatsapp Library",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
package/readme.md CHANGED
@@ -1,35 +1,41 @@
1
1
  # wa-api
2
2
 
3
- Leichte Bibliothek zur Verwaltung mehrerer WhatsApp-Sessions – mit **einer** universellen `sendMessage`-Funktion und direkter `relayMessage`-Unterstützung für alle fortgeschrittenen Szenarien.
3
+ Leichte Bibliothek zur Verwaltung mehrerer WhatsApp-Sessions – mit einer zentralen `sendMessage`-Funktion und direktem Zugriff auf Baileys’ `relayMessage`.
4
4
 
5
5
  ---
6
6
 
7
7
  ## 📑 Inhaltsverzeichnis
8
8
 
9
- 1. [Installation](#installation)
10
- 2. [Import & Setup](#import--setup)
9
+ 1. [Kurzübersicht](#kurzübersicht)
10
+ 2. [Installation & Setup](#installation--setup)
11
11
  3. [Session Management](#session-management)
12
- 4. [Nachrichten senden via `sendMessage`](#nachrichten-senden-via-sendmessage)
13
- 5. [Low-level `relayMessage` Beispiele](#low-level-relaymessage-beispiele)
14
-
15
- * [ProtocolMessage: Nachricht löschen (Revoke)](#protocolmessage-nachricht-löschen-revoke)
16
- * [Ephemeral-Modus (Gruppen)](#ephemeral-modus-gruppen)
17
- * [Status-Update (Story)](#status-update-story)
18
- * [Weiterleiten (Forward)](#weiterleiten-forward)
19
- * [Profilbild aktualisieren](#profilbild-aktualisieren)
20
- * [Chat als gelesen markieren](#chat-als-gelesen-markieren)
12
+ 4. [Nachrichten senden (`sendMessage`)](#nachrichten-senden-sendmessage)
13
+ 5. [Low-Level Relay (`relayMessage`)](#low-level-relay-relaymessage)
21
14
  6. [Listener](#listener)
22
15
  7. [Fehlerbehandlung](#fehlerbehandlung)
16
+ 8. [Support](#support)
23
17
 
24
18
  ---
25
19
 
26
- ## 📦 Installation
20
+ ## 🚀 Kurzübersicht
21
+
22
+ **wa-api** bietet:
23
+
24
+ * **Multi-Session**: Verwaltung beliebig vieler WhatsApp-Sessions in einer App.
25
+ * **One-Stop Messaging**: Eine einzige `sendMessage`-Funktion für **Text**, **Media**, **Umfragen**, **Reactions**, **Status-Updates** u.v.m.
26
+ * **Low-Level Relay**: Direkter Zugriff auf Baileys’ `relayMessage` für Spezialfälle.
27
+ * **Automatisches Caching** und **JID-Konvertierung**.
28
+ * **Konsistentes Error-Handling** mit `WhatsappError`.
29
+
30
+ ---
31
+
32
+ ## 📦 Installation & Setup
27
33
 
28
34
  ```bash
29
35
  npm install @deathnaitsa/wa-api@latest
30
36
  ```
31
37
 
32
- ## 🔌 Import & Setup
38
+ **Import**
33
39
 
34
40
  ```js
35
41
  // CommonJS
@@ -39,149 +45,103 @@ const wa = require('@deathnaitsa/wa-api');
39
45
  import * as wa from '@deathnaitsa/wa-api';
40
46
  ```
41
47
 
42
- ## 🚀 Session Management
48
+ ---
49
+
50
+ ## 🔑 Session Management
51
+
52
+ | Funktion | Beschreibung |
53
+ | ----------------------------------------------------- | ------------------------------------------------- |
54
+ | `wa.startSession(id)` | Neue Session starten + QR-Code im Terminal zeigen |
55
+ | `wa.startSessionWithPairingCode(id, { phoneNumber })` | Direkt per Pairing-Code starten |
56
+ | `wa.getAllSession()` | Array aller aktiven Session-IDs |
57
+ | `wa.getSession(id)` | Metadaten einer Session abrufen |
58
+ | `wa.loadSessionsFromStorage()` | Alle gespeicherten Sessions aus Ordner laden |
59
+
60
+ **Beispiel**
43
61
 
44
62
  ```js
45
- await wa.startSession('session1');
46
- await wa.startSessionWithPairingCode('session2', { phoneNumber: '491234567890' });
47
- const all = wa.getAllSession();
48
- const one = wa.getSession('session1');
49
- const loaded = await wa.loadSessionsFromStorage();
63
+ await wa.startSession('meineSession');
64
+ const sessions = wa.getAllSession();
65
+ console.log(sessions);
50
66
  ```
51
67
 
52
- ## 💬 Nachrichten senden via `sendMessage`
68
+ ---
53
69
 
54
- Eine **zentrale** Funktion für **alle** Nachrichtentypen:
70
+ ## 💬 Nachrichten senden (`sendMessage`)
55
71
 
56
72
  ```js
57
73
  await wa.sendMessage(
58
- sessionId, // Session-ID
59
- jidOrPhone, // JID oder Telefonnummer
60
- content, // AnyMessageContent
61
- options // MiscMessageGenerationOptions
74
+ sessionId, // string
75
+ jidOrPhone, // string (z.B. '491234567890@c.us')
76
+ content, // AnyMessageContent-Objekt
77
+ options // MiscMessageGenerationOptions (optional)
62
78
  );
63
79
  ```
64
80
 
65
- ### Beispiele
66
-
67
- | Typ | Kurzbeschreibung | content | options |
68
- | -------------- | -------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------- |
69
- | Text | Normale Textnachricht | `{ text: 'Hallo Welt!' }` | `{ quoted, mentions }` |
70
- | Bild | Sende Bild | `{ image:{url:'./img.png'},caption:'Bild',viewOnce:true }` | `{ quoted }` |
71
- | Video | Sende Video | `{ video:{url:'./vid.mp4'},caption:'Video' }` | `{ }` |
72
- | GIF | Sende GIF (MP4 + Playback) | `{ video:{url:'./gif.mp4'},gifPlayback:true }` | `{ }` |
73
- | Audio | Voice Note (OGG/Opus) | `{ audio: fs.createReadStream('test.ogg'),mimetype:'audio/ogg',ptt:true }` | `{ quoted }` |
74
- | Dokument | Datei | `{ document:{url:'./doc.pdf',filename:'Doc.pdf'} }` | `{ }` |
75
- | Poll | Umfrage | `{ pollCreationMessage:{name:'Umfrage',options:[{name:'A'},{name:'B'}],selectableCount:1} }` | `{ quoted }` |
76
- | React | Emoji-Reaktion | `{ react:{text:'👍',key:msg.key} }` | `{ quoted }` |
77
- | Delete | Löschen (Revoke) | `{ delete: msg.key }` | `{ }` |
78
- | Pin | Pin/Unpin | `{ pin:{type:1,time:3600,key:msg.key} }` | `{ }` |
79
- | Contacts | Kontaktkarte | `{ contacts:{displayName:'Max',contacts:[{vcard}] } }` | `{ }` |
80
- | Location | Standort | `{ location:{degreesLatitude:52.52,degreesLongitude:13.405} }` | `{ }` |
81
- | Forward | Weiterleiten | `{ forward: origMsg }` | `{ quoted }` |
82
- | Status (Story) | Status-Update | `{ video:{url:'story.mp4'},caption:'Status' }` | `{ statusJidList:[...JIDs] }` |
81
+ | Typ | Beispiel-Content | Beispiel-Options |
82
+ | ------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------ |
83
+ | **Text** | `{ text: 'Hallo Welt!' }` | `{ quoted, mentions }` |
84
+ | **Bild** | `{ image:{ url:'./bild.png' }, caption:'Bild', viewOnce:true }` | `{ quoted }` |
85
+ | **Video** | `{ video:{ url:'./video.mp4' }, caption:'Video' }` | `{ }` |
86
+ | **GIF** | `{ video:{ url:'./gif.mp4' }, gifPlayback:true }` | `{ }` |
87
+ | **Audio** | `{ audio:{ url:'./test.ogg' }, mimetype:'audio/ogg', ptt:true }` | `{ quoted }` |
88
+ | **Dokument** | `{ document:{ url:'./doc.pdf', filename:'Doc.pdf' } }` | `{ }` |
89
+ | **Poll** | `{ pollCreationMessage:{ name:'Umfrage', options:[{name:'A'},{name:'B'}], selectableCount:1 } }` | `{ quoted }` |
90
+ | **React** | `{ react:{ text:'👍', key:msg.key } }` | `{ quoted }` |
91
+ | **Delete** | `{ delete: msg.key }` | `{ }` |
92
+ | **Pin** | `{ pin:{ type:1, time:3600, key:msg.key } }` | `{ }` |
93
+ | **Contacts** | `{ contacts:{ displayName:'Max', contacts:[{ vcard }] } }` | `{ }` |
94
+ | **Location** | `{ location:{ degreesLatitude:52.52, degreesLongitude:13.405 } }` | `{ }` |
95
+ | **Forward** | `{ forward: origMsg }` | `{ quoted }` |
96
+ | **Status** | `{ video:{ url:'story.mp4' }, caption:'Status' }` | `{ statusJidList:['...@s.whatsapp.net'] }` |
83
97
 
84
98
  ---
85
99
 
86
- ## 🔄 Low-level `relayMessage` Beispiele
100
+ ## 🔄 Low-Level Relay (`relayMessage`)
87
101
 
88
- Direktes Senden von WAMessage-Stanzas für Spezialfälle.
102
+ Direktes Senden von XML-Stanzas. **Use Cases**:
89
103
 
90
104
  ### ProtocolMessage: Nachricht löschen (Revoke)
91
105
 
92
106
  ```js
93
- const deleteNode = {
94
- protocolMessage: {
95
- key: { remoteJid: chatJid, fromMe: true, id: targetId },
96
- type: 7 // MESSAGE_REVOKE
97
- }
98
- };
99
- await wa.relayMessage(
100
- sessionId,
101
- chatJid,
102
- deleteNode,
103
- { messageId: targetId }
104
- );
107
+ const deleteNode = { protocolMessage:{ key:{ remoteJid, fromMe:true, id:targetId }, type:7 } };
108
+ await wa.relayMessage(sessionId, remoteJid, deleteNode, { messageId: targetId });
105
109
  ```
106
110
 
107
111
  ### Ephemeral-Modus (Gruppen)
108
112
 
109
113
  ```js
110
- // 24h Ephemeral ein
111
- await wa.relayMessage(
112
- sessionId,
113
- groupJid,
114
- { disappearingMessagesInChat: Defaults.WA_DEFAULT_EPHEMERAL },
115
- {}
116
- );
117
- // Ephemeral aus
118
- await wa.relayMessage(
119
- sessionId,
120
- groupJid,
121
- { disappearingMessagesInChat: 0 },
122
- {}
123
- );
114
+ await wa.relayMessage(sessionId, groupJid, { disappearingMessagesInChat: 86400 }, {});
115
+ await wa.relayMessage(sessionId, groupJid, { disappearingMessagesInChat: 0 }, {});
124
116
  ```
125
117
 
126
118
  ### Status-Update (Story)
127
119
 
128
120
  ```js
129
- const storyNode = {
130
- videoMessage: { url: './story.mp4' },
131
- caption: 'Meine Story'
132
- };
133
- await wa.relayMessage(
134
- sessionId,
135
- 'status@broadcast',
136
- storyNode,
137
- { statusJidList: ['491234567890@s.whatsapp.net'] }
138
- );
121
+ const node = { videoMessage:{ url:'./story.mp4' }, caption:'Meine Story' };
122
+ await wa.relayMessage(sessionId, 'status@broadcast', node, { statusJidList });
139
123
  ```
140
124
 
141
125
  ### Weiterleiten (Forward)
142
126
 
143
127
  ```js
144
128
  const origMsg = getMessageFromStore();
145
- const forwardNode = { forward: origMsg };
146
- await wa.relayMessage(
147
- sessionId,
148
- chatJid,
149
- forwardNode,
150
- { messageId: origMsg.key.id }
151
- );
129
+ const node = { forward: origMsg };
130
+ await wa.relayMessage(sessionId, chatJid, node, { messageId: origMsg.key.id });
152
131
  ```
153
132
 
154
133
  ### Profilbild aktualisieren
155
134
 
156
135
  ```js
157
- const updateNode = {
158
- profilePictureChange: {
159
- displayPicture: fs.readFileSync('./newprofile.jpg')
160
- }
161
- };
162
- await wa.relayMessage(
163
- sessionId,
164
- userJid,
165
- updateNode,
166
- { messageId: 'nishiProfileUpdate' }
167
- );
136
+ const node = { profilePictureChange:{ displayPhoneNumber:true, displayName:true } };
137
+ await wa.relayMessage(sessionId, userJid, node, { messageId:'nishiProfPic' });
168
138
  ```
169
139
 
170
140
  ### Chat als gelesen markieren
171
141
 
172
142
  ```js
173
- const readNode = {
174
- protocolMessage: {
175
- key: { remoteJid: chatJid },
176
- type: 3 // READ
177
- }
178
- };
179
- await wa.relayMessage(
180
- sessionId,
181
- chatJid,
182
- readNode,
183
- { messageId: 'nishiMarkRead' }
184
- );
143
+ const node = { protocolMessage:{ key:{ remoteJid:chatJid }, type:3 } };
144
+ await wa.relayMessage(sessionId, chatJid, node, { messageId:'nishiRead' });
185
145
  ```
186
146
 
187
147
  ---
@@ -191,19 +151,25 @@ await wa.relayMessage(
191
151
  ```js
192
152
  wa.onConnected(id => console.log('Online:', id));
193
153
  wa.onQRUpdated(info => console.log('QR:', info));
194
- wa.onMessageReceived(msg => console.log('Nachricht:', msg));
154
+ wa.onMessageReceived(msg => console.log('Msg:', msg));
195
155
  ```
196
156
 
157
+ ---
158
+
197
159
  ## ⚠️ Fehlerbehandlung
198
160
 
199
161
  ```js
200
162
  try {
201
163
  await wa.sendMessage(...);
202
- } catch(e) {
203
- console.error(e);
164
+ } catch (e) {
165
+ if (e instanceof wa.WhatsappError) console.error(e.message);
204
166
  }
205
167
  ```
206
168
 
207
169
  ---
208
170
 
209
- © 2025 `@deathnaitsa/wa-api` • Support: [sebloidl13@gmail.com](mailto:sebloidl13@gmail.com)
171
+ ## 🆘 Support
172
+
173
+ **E-Mail:** [sebloidl13@gmail.com](mailto:sebloidl13@gmail.com)
174
+
175
+ © 2025 `@deathnaitsa/wa-api`