whatsapp-web.js 1.15.8 → 1.16.0

package/.env.example

@@ -1,2 +1,3 @@
-WWEBJS_TEST_SESSION_PATH=test_session.json
-WWEBJS_TEST_REMOTE_ID=XXXXXXXXXX@c.us
+WWEBJS_TEST_REMOTE_ID=XXXXXXXXXX@c.us
+WWEBJS_TEST_CLIENT_ID=authenticated
+WWEBJS_TEST_MD=1

package/README.md

@@ -47,43 +47,14 @@ client.initialize();
 
 Take a look at [example.js](https://github.com/pedroslopez/whatsapp-web.js/blob/master/example.js) for another example with more use cases.
 
-## Remote Access
+For more information on saving and restoring sessions, check out the available [Authentication Strategies](https://wwebjs.dev/guide/authentication.html).
 
-You could also connect to any previously existing browser instance:
-
-```js
-const client = new Client({ 
-    puppeteer: {
-        browserWSEndpoint: `ws://localhost:3000`
-    }
-});
-```
-
-### Docker
-
-1) Installing a browser using browserless:
-
-```
-docker run \
-  --rm \
-  -p 3000:3000 \
-  -e "MAX_CONCURRENT_SESSIONS=1" \
-  browserless/chrome:latest
-```
-
-Reference: https://docs.browserless.io/docs/docker-quickstart.html
-
-### Remote Debugging
-
-2) Running a browser with websocket remote debugging enabled:
-> chrome.exe --remote-debugging-port=9222
-
-After that check the following webpage and check http://127.0.0.1:9220/json and get the **webSocketDebuggerUrl**
 
 ## Supported features
 
 | Feature  | Status |
 | ------------- | ------------- |
+| Multi Device  | ✅  |
 | Send messages  | ✅  |
 | Receive messages  | ✅  |
 | Send media (images/audio/documents)  | ✅  |
@@ -116,11 +87,13 @@ Something missing? Make an issue and let us know!
 
 Pull requests are welcome! If you see something you'd like to add, please do. For drastic changes, please open an issue first.
 
-## Donating
+## Supporting the project
 
-You can support the maintainer of this project through the link below
+You can support the maintainer of this project through the links below
 
-[![Support via PayPal](https://cdn.rawgit.com/twolfson/paypal-github-button/1.0.0/dist/button.svg)](https://www.paypal.me/psla/)
+- [Support via GitHub Sponsors](https://github.com/sponsors/pedroslopez)
+- [Support via PayPal](https://www.paypal.me/psla/)
+- [Sign up for DigitalOcean](https://m.do.co/c/73f906a36ed4) and get $100 in credit when you sign up (Referral)
 
 ## Disclaimer
 

package/example.js

@@ -1,22 +1,9 @@
-const fs = require('fs');
-const { Client, Location, List, Buttons } = require('./index');
+const { Client, Location, List, Buttons, LocalAuth } = require('./index');
 
-const SESSION_FILE_PATH = './session.json';
-let sessionCfg;
-if (fs.existsSync(SESSION_FILE_PATH)) {
-    sessionCfg = require(SESSION_FILE_PATH);
-}
-
-const client = new Client({ puppeteer: { headless: false }, session: sessionCfg });
-// You can use an existing session and avoid scanning a QR code by adding a "session" object to the client options.
-// This object must include WABrowserId, WASecretBundle, WAToken1 and WAToken2.
-
-// You also could connect to an existing instance of a browser
-// { 
-//    puppeteer: {
-//        browserWSEndpoint: `ws://localhost:3000`
-//    }
-// }
+const client = new Client({
+    authStrategy: new LocalAuth(),
+    puppeteer: { headless: false }
+});
 
 client.initialize();
 
@@ -25,18 +12,12 @@ client.on('qr', (qr) => {
     console.log('QR RECEIVED', qr);
 });
 
-client.on('authenticated', (session) => {
-    console.log('AUTHENTICATED', session);
-    sessionCfg=session;
-    fs.writeFile(SESSION_FILE_PATH, JSON.stringify(session), function (err) {
-        if (err) {
-            console.error(err);
-        }
-    });
+client.on('authenticated', () => {
+    console.log('AUTHENTICATED');
 });
 
 client.on('auth_failure', msg => {
-    // Fired if session restore was unsuccessfull
+    // Fired if session restore was unsuccessful
     console.error('AUTHENTICATION FAILURE', msg);
 });
 
@@ -124,9 +105,8 @@ client.on('message', async msg => {
         client.sendMessage(msg.from, `
             *Connection info*
             User name: ${info.pushname}
-            My number: ${info.me.user}
+            My number: ${info.wid.user}
             Platform: ${info.platform}
-            WhatsApp version: ${info.phone.wa_version}
         `);
     } else if (msg.body === '!mediainfo' && msg.hasMedia) {
         const attachmentData = await msg.downloadMedia();
@@ -267,12 +247,6 @@ client.on('group_update', (notification) => {
     console.log('update', notification);
 });
 
-client.on('change_battery', (batteryInfo) => {
-    // Battery percentage for attached device has changed
-    const { battery, plugged } = batteryInfo;
-    console.log(`Battery: ${battery}% - Charging? ${plugged}`);
-});
-
 client.on('change_state', state => {
     console.log('CHANGE STATE', state );
 });

package/index.d.ts

@@ -84,6 +84,9 @@ declare namespace WAWebJS {
         /** Returns the contact ID's profile picture URL, if privacy settings allow it */
         getProfilePicUrl(contactId: string): Promise<string>
 
+        /** Gets the Contact's common groups with you. Returns empty array if you don't have any common group. */
+        getCommonGroups(contactId: string): Promise<ChatId[]>
+
         /** Gets the current connection state for the client */
         getState(): Promise<WAState>
 
@@ -118,6 +121,9 @@ declare namespace WAWebJS {
         /** Marks the client as online */
         sendPresenceAvailable(): Promise<void>
 
+        /** Marks the client as offline */
+        sendPresenceUnavailable(): Promise<void>
+
         /** Mark as seen for the Chat */
         sendSeen(chatId: string): Promise<boolean>
 
@@ -134,7 +140,7 @@ declare namespace WAWebJS {
          * Sets the current user's display name
          * @param displayName New display name
          */
-        setDisplayName(displayName: string): Promise<void>
+        setDisplayName(displayName: string): Promise<boolean>
 
         /** Changes and returns the archive state of the Chat */
         unarchiveChat(chatId: string): Promise<boolean>
@@ -150,11 +156,16 @@ declare namespace WAWebJS {
 
         /** Emitted when authentication is successful */
         on(event: 'authenticated', listener: (
-            /** Object containing session information. Can be used to restore the session */
-            session: ClientSession
+            /** 
+             * Object containing session information, when using LegacySessionAuth. Can be used to restore the session
+             */
+            session?: ClientSession
         ) => void): this
 
-        /** Emitted when the battery percentage for the attached device changes */
+        /** 
+         * Emitted when the battery percentage for the attached device changes
+         * @deprecated 
+         */
         on(event: 'change_battery', listener: (batteryInfo: BatteryInfo) => void): this
 
         /** Emitted when the connection state changes */
@@ -249,14 +260,12 @@ declare namespace WAWebJS {
 
     /** Current connection information */
     export interface ClientInfo {
-        /** 
-         * Current user ID 
-         * @deprecated Use .wid instead 
-         */
-        me: ContactId
         /** Current user ID */
         wid: ContactId
-        /** Information about the phone this client is connected to */
+        /** 
+         * Information about the phone this client is connected to.  Not available in multi-device. 
+         * @deprecated 
+         */
         phone: ClientInfoPhone
         /** Platform the phone is running on */
         platform: string
@@ -267,7 +276,10 @@ declare namespace WAWebJS {
         getBatteryStatus: () => Promise<BatteryInfo>
     }
 
-    /** Information about the phone this client is connected to */
+    /** 
+     * Information about the phone this client is connected to 
+     * @deprecated
+     */
     export interface ClientInfoPhone {
         /** WhatsApp Version running on the phone */
         wa_version: string
@@ -284,23 +296,22 @@ declare namespace WAWebJS {
     /** Options for initializing the whatsapp client */
     export interface ClientOptions {
         /** Timeout for authentication selector in puppeteer
-         * @default 45000 */
+         * @default 0 */
         authTimeoutMs?: number,
         /** Puppeteer launch options. View docs here: https://github.com/puppeteer/puppeteer/ */
         puppeteer?: puppeteer.LaunchOptions & puppeteer.BrowserLaunchArgumentOptions & puppeteer.BrowserConnectOptions
-        /** Refresh interval for qr code (how much time to wait before checking if the qr code has changed)
-         * @default 20000 */
-        qrRefreshIntervalMs?: number
-        /** Timeout for qr code selector in puppeteer
-         * @default 45000 */
-        qrTimeoutMs?: number,
-		/** How many times should the qrcode be refreshed before giving up
+		/** Determines how to save and restore sessions. Will use LegacySessionAuth if options.session is set. Otherwise, NoAuth will be used. */
+        authStrategy?: AuthStrategy,
+        /** How many times should the qrcode be refreshed before giving up
 		 * @default 0 (disabled) */
 		qrMaxRetries?: number,
-        /** Restart client with a new session (i.e. use null 'session' var) if authentication fails
-         * @default false */
+        /** 
+         * @deprecated This option should be set directly on the LegacySessionAuth
+         */
         restartOnAuthFail?: boolean
-        /** Whatsapp session to restore. If not set, will start a new session */
+        /** 
+         * @deprecated Only here for backwards-compatibility. You should move to using LocalAuth, or set the authStrategy to LegacySessionAuth explicitly.  
+         */
         session?: ClientSession
         /** If another whatsapp web session is detected (another browser), take over the session in the current browser
          * @default false */
@@ -316,7 +327,52 @@ declare namespace WAWebJS {
         ffmpegPath?: string
     }
 
-    /** Represents a Whatsapp client session */
+    /**
+     * Base class which all authentication strategies extend
+     */
+    export abstract class AuthStrategy {
+        setup: (client: Client) => void;
+        beforeBrowserInitialized: () => Promise<void>;
+        afterBrowserInitialized: () => Promise<void>;
+        onAuthenticationNeeded: () => Promise<{
+            failed?: boolean; 
+            restart?: boolean; 
+            failureEventPayload?: any
+        }>;
+        getAuthEventPayload: () => Promise<any>;
+        logout: () => Promise<void>;
+    }
+
+    /**
+     * No session restoring functionality
+     * Will need to authenticate via QR code every time
+     */
+    export class NoAuth extends AuthStrategy {}
+
+    /**
+     * Local directory-based authentication
+     */
+    export class LocalAuth extends AuthStrategy {
+        constructor(options?: {
+            clientId?: string,
+            dataPath?: string
+        })
+    }
+
+    /**
+     * Legacy session auth strategy
+     * Not compatible with multi-device accounts.
+     */
+     export class LegacySessionAuth extends AuthStrategy {
+        constructor(options?: {
+            session?: ClientSession,
+            restartOnAuth?: boolean,
+        })
+    }
+
+    /** 
+     * Represents a WhatsApp client session
+     */
     export interface ClientSession {
         WABrowserId: string,
         WASecretBundle: string,
@@ -324,6 +380,9 @@ declare namespace WAWebJS {
         WAToken2: string,
     }
 
+    /** 
+     * @deprecated
+     */
     export interface BatteryInfo {
         /** The current battery percentage */
         battery: number,
@@ -556,6 +615,8 @@ declare namespace WAWebJS {
         hasMedia: boolean,
         /** Indicates if the message was sent as a reply to another message */
         hasQuotedMsg: boolean,
+        /** Indicates the duration of the message in seconds */
+        duration: string,
         /** ID that represents the message */
         id: MessageId,
         /** Indicates if the message was forwarded */
@@ -608,6 +669,13 @@ declare namespace WAWebJS {
         selectedButtonId?: string,
         /** Selected list row ID */
         selectedRowId?: string,
+        /** Returns message in a raw format */
+        rawData: object,
+        /* 
+        * Reloads this Message object's data in-place with the latest values from WhatsApp Web. 
+        * Note that the Message must still be in the web app cache for this to work, otherwise will return null.
+        */
+        reload: () => Promise<Message>,
         /** Accept the Group V4 Invite in message */
         acceptGroupV4Invite: () => Promise<{status: number}>,
         /** Deletes the message from the chat */
@@ -679,7 +747,7 @@ declare namespace WAWebJS {
 
     /** Options for sending a message */
     export interface MessageSendOptions {
-        /** Show links preview */
+        /** Show links preview. Has no effect on multi-device accounts. */
         linkPreview?: boolean
         /** Send audio as voice message */
         sendAudioAsVoice?: boolean
@@ -741,7 +809,7 @@ declare namespace WAWebJS {
         static fromUrl: (url: string, options?: MediaFromURLOptions) => Promise<MessageMedia>
     }
 
-    export type MessageContent = string | MessageMedia | Location | Contact | Contact[] | List | Buttons
+    export type MessageContent = string | MessageMedia | Location | Contact | Contact[] | List | Buttons 
 
     /**
      * Represents a Contact on WhatsApp
@@ -834,6 +902,9 @@ declare namespace WAWebJS {
 
         /** Gets the Contact's current "about" info. Returns null if you don't have permission to read their status.  */
         getAbout: () => Promise<string | null>,
+        
+        /** Gets the Contact's common groups with you. Returns empty array if you don't have any common group. */
+        getCommonGroups: () => Promise<ChatId[]>
 
     }
 
@@ -977,7 +1048,7 @@ declare namespace WAWebJS {
     }
 
     /** Promotes or demotes participants by IDs to regular users or admins */
-    export type ChangeParticipantsPermisions = 
+    export type ChangeParticipantsPermissions = 
         (participantIds: Array<string>) => Promise<{ status: number }>
 
     /** Adds or removes a list of participants by ID to the group */
@@ -1007,13 +1078,13 @@ declare namespace WAWebJS {
         /** Removes a list of participants by ID to the group */
         removeParticipants: ChangeGroupParticipants;
         /** Promotes participants by IDs to admins */
-        promoteParticipants: ChangeParticipantsPermisions;
+        promoteParticipants: ChangeParticipantsPermissions;
         /** Demotes participants by IDs to regular users */
-        demoteParticipants: ChangeParticipantsPermisions;
+        demoteParticipants: ChangeParticipantsPermissions;
         /** Updates the group subject */
-        setSubject: (subject: string) => Promise<void>;
+        setSubject: (subject: string) => Promise<boolean>;
         /** Updates the group description */
-        setDescription: (description: string) => Promise<void>;
+        setDescription: (description: string) => Promise<boolean>;
         /** Updates the group settings to only allow admins to send messages 
          * @param {boolean} [adminsOnly=true] Enable or disable this option 
          * @returns {Promise<boolean>} Returns true if the setting was properly updated. This can return false if the user does not have the necessary permissions.

package/index.js

@@ -21,5 +21,11 @@ module.exports = {
     ProductMetadata: require('./src/structures/ProductMetadata'),
     List: require('./src/structures/List'),
     Buttons: require('./src/structures/Buttons'),
+    
+    // Auth Strategies
+    NoAuth: require('./src/authStrategies/NoAuth'),
+    LocalAuth: require('./src/authStrategies/LocalAuth'),
+    LegacySessionAuth: require('./src/authStrategies/LegacySessionAuth'),
+    
     ...Constants
 };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "whatsapp-web.js",
-  "version": "1.15.8",
+  "version": "1.16.0",
   "description": "Library for interacting with the WhatsApp Web API ",
   "main": "./index.js",
   "typings": "./index.d.ts",
   "scripts": {
-    "test": "mocha tests --recursive",
+    "test": "mocha tests --recursive --timeout 5000",
     "test-single": "mocha",
     "shell": "node --experimental-repl-await ./shell.js",
     "generate-docs": "node_modules/.bin/jsdoc --configure .jsdoc.json --verbose"
@@ -35,12 +35,12 @@
     "mime": "^3.0.0",
     "node-fetch": "^2.6.5",
     "node-webpmux": "^3.1.0",
-    "puppeteer": "^13.0.0",
-    "sharp": "^0.28.3"
+    "puppeteer": "^13.0.0"
   },
   "devDependencies": {
     "@types/node-fetch": "^2.5.12",
     "chai": "^4.3.4",
+    "chai-as-promised": "^7.1.1",
     "dotenv": "^16.0.0",
     "eslint": "^8.4.1",
     "eslint-plugin-mocha": "^10.0.3",

package/shell.js

@@ -2,24 +2,17 @@
  * ==== wwebjs-shell ====
  * Used for quickly testing library features
  * 
- * Running `npm run shell` will start WhatsApp Web in headless mode 
+ * Running `npm run shell` will start WhatsApp Web with headless=false
  * and then drop you into Node REPL with `client` in its context. 
  */
 
 const repl = require('repl');
-const fs = require('fs');
 
-const { Client } = require('./index');
-
-const SESSION_FILE_PATH = './session.json';
-let sessionCfg;
-if (fs.existsSync(SESSION_FILE_PATH)) {
-    sessionCfg = require(SESSION_FILE_PATH);
-}
+const { Client, LocalAuth } = require('./index');
 
 const client = new Client({
     puppeteer: { headless: false }, 
-    session: sessionCfg 
+    authStrategy: new LocalAuth()
 });
 
 console.log('Initializing...');
@@ -30,6 +23,10 @@ client.on('qr', () => {
     console.log('Please scan the QR code on the browser.');
 });
 
+client.on('authenticated', (session) => {
+    console.log(JSON.stringify(session));
+});
+
 client.on('ready', () => {
     const shell = repl.start('wwebjs> ');
     shell.context.client = client;