chore: add missing types in JSDoc/TSDoc (ClientOptions, ClientInfo, MessageSendOptions, Session) (#286)

* chore: add ClientOptions and ClientInfo in JSDoc * chore: add MessageSendOptions type * chore: add ClientSession type in JSDoc * chore: remove @todo from createGroup (was already solved) Co-authored-by: Pedro Lopez <pedroslopez@me.com>
2026-04-22 21:40:08 +00:00 · 2020-08-03 03:52:37 -03:00
parent bfea74f567
commit 5c84a1651d
4 changed files with 124 additions and 74 deletions
--- a/index.d.ts
+++ b/index.d.ts
@@ -7,10 +7,7 @@ declare namespace WAWebJS {
  export class Client extends EventEmitter {
    constructor(options: ClientOptions)
    
-    /** 
-     * Current connection information 
-     * @todo add this in the official docs 
-     */
+    /** Current connection information */
    public info: ClientInfo

    /**Accepts an invitation to join a group */
@@ -26,8 +23,6 @@ declare namespace WAWebJS {
     * Create a new group
     * @param name group title
     * @param participants an array of Contacts or contact IDs to add to the group
-     * 
-     * @todo improve return type in the official docs
     */
    createGroup(name: string, participants: Contact[] | string[]): Promise<CreateGroupResult>

@@ -223,25 +218,32 @@ declare namespace WAWebJS {
    os_build_number: string
  }

-  /**
-   * Options for initializing the whatsapp client
-   * @todo add these in the official docs
-   */
+  /** Options for initializing the whatsapp client */
  export interface ClientOptions {
-    puppeteer?: puppeteer.LaunchOptions
-    /** Whatsapp session to restore. If not set, will start a new session  */
-    session?: ClientSession,
-    /** @default 45000 */
-    qrTimeoutMs?: number,
-    /** @default 20000 */
-    qrRefreshIntervalMs?: number,
-    /** @default 45000 */
+    /** Timeout for authentication selector in puppeteer
+     * @default 45000 */
    authTimeoutMs?: number,
-    /** @default false */
+    /** Puppeteer launch options. View docs here: https://github.com/puppeteer/puppeteer/ */
+    puppeteer?: puppeteer.LaunchOptions
+    /** 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,
+    /** Restart client with a new session (i.e. use null 'session' var) if authentication fails
+     * @default false */
+    restartOnAuthFail?: boolean
+    /** Whatsapp session to restore. If not set, will start a new session */
+    session?: ClientSession
+    /** If another whatsapp web session is detected (another browser), take over the session in the current browser
+     * @default false */
    takeoverOnConflict?: boolean,
-    /** @default 0 */
+    /** How much time to wait before taking over the session
+     * @default 0 */
    takeoverTimeoutMs?: number,
-    /** @default 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.109 Safari/537.36' */
+    /** User agent to use in puppeteer.
+     * @default 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.109 Safari/537.36' */
    userAgent?: string
  }

@@ -451,7 +453,7 @@ declare namespace WAWebJS {
     */
    to: string,
    /** Message type */
-    type: string,
+    type: MessageTypes,

    /** Deletes the message from the chat */
    delete: (everyone?: boolean) => Promise<void>,
@@ -487,10 +489,23 @@ declare namespace WAWebJS {
    longitude: string,
  }

-  /**
-   * Options for sending a message
-   * @todo add more specific type for the object */
-  export type MessageSendOptions = object
+  /** Options for sending a message */
+  export interface MessageSendOptions {
+    /** Show links preview */
+    linkPreview?: boolean
+    /** Send audio as voice message */
+    sendAudioAsVoice?: boolean
+    /** Image or videos caption */
+    caption?: string
+    /** Id of the message that is being quoted (or replied to) */
+    quotedMessageId?: string
+    /** Contacts that are being mentioned in the message */
+    mentions?: Contact[]
+    /** Send 'seen' status */
+    sendSeen?: boolean
+    /** Media to be sent */
+    media?: MessageMedia
+  }

  export interface MessageMedia {
    data: string,
--- a/src/Client.js
+++ b/src/Client.js
@@ -15,7 +15,21 @@ const { ClientInfo, Message, MessageMedia, Contact, Location, GroupNotification
 /**
 * Starting point for interacting with the WhatsApp Web API
 * @extends {EventEmitter}
- * @param {object} options
+ * @param {object} options - Client options
+ * @param {number} options.authTimeoutMs - Timeout for authentication selector in puppeteer
+ * @param {object} options.puppeteer - Puppeteer launch options. View docs here: https://github.com/puppeteer/puppeteer/
+ * @param {number} options.qrRefreshIntervalMs - Refresh interval for qr code (how much time to wait before checking if the qr code has changed)
+ * @param {number} options.qrTimeoutMs - Timeout for qr code selector in puppeteer
+ * @param {string} options.restartOnAuthFail  - Restart client with a new session (i.e. use null 'session' var) if authentication fails
+ * @param {object} options.session - Whatsapp session to restore. If not set, will start a new session
+ * @param {string} options.session.WABrowserId
+ * @param {string} options.session.WASecretBundle
+ * @param {string} options.session.WAToken1
+ * @param {string} options.session.WAToken2
+ * @param {number} options.takeoverOnConflict - If another whatsapp web session is detected (another browser), take over the session in the current browser
+ * @param {number} options.takeoverTimeoutMs - How much time to wait before taking over the session
+ * @param {string} options.userAgent - User agent to use in puppeteer
+ * 
 * @fires Client#qr
 * @fires Client#authenticated
 * @fires Client#auth_failure
@@ -146,6 +160,10 @@ class Client extends EventEmitter {
         * Emitted when authentication is successful
         * @event Client#authenticated
         * @param {object} session Object containing session information. Can be used to restore the session.
+         * @param {string} session.WABrowserId
+         * @param {string} session.WASecretBundle
+         * @param {string} session.WAToken1
+         * @param {string} session.WAToken2
         */
        this.emit(Events.AUTHENTICATED, session);

@@ -156,6 +174,10 @@ class Client extends EventEmitter {
        await page.evaluate(LoadUtils);

        // Expose client info
+        /**
+         * Current connection information
+         * @type {ClientInfo}
+         */
        this.info = new ClientInfo(this, await page.evaluate(() => {
            return window.Store.Conn.serialize();
        }));
@@ -393,11 +415,24 @@ class Client extends EventEmitter {
        return result;
    }

+    /**
+     * Message options.
+     * @typedef {Object} MessageSendOptions
+     * @property {boolean} [linkPreview=true] - Show links preview
+     * @property {boolean} [sendAudioAsVoice=false] - Send audio as voice message
+     * @property {string} [caption] - Image or video caption
+     * @property {string} [quotedMessageId] - Id of the message that is being quoted (or replied to)
+     * @property {Contact[]} [mentions] - Contacts that are being mentioned in the message
+     * @property {boolean} [sendSeen=true] - Mark the conversation as seen after sending the message
+     * @property {boolean} [media] - Media to be sent
+     */
+
    /**
     * Send a message to a specific chatId
     * @param {string} chatId
     * @param {string|MessageMedia|Location} content
-     * @param {object} options 
+     * @param {MessageSendOptions} [options] - Options used when sending the message
+     * 
     * @returns {Promise<Message>} Message that was just sent
     */
    async sendMessage(chatId, content, options = {}) {
--- a/src/structures/Chat.js
+++ b/src/structures/Chat.js
@@ -63,7 +63,7 @@ class Chat extends Base {
    /**
     * Send a message to this chat
     * @param {string|MessageMedia|Location} content
-     * @param {object} options 
+     * @param {MessageSendOptions} [options] 
     * @returns {Promise<Message>} Message that was just sent
     */
    async sendMessage(content, options) {
--- a/src/structures/Message.js
+++ b/src/structures/Message.js
@@ -173,8 +173,8 @@ class Message extends Base {
     * in the same Chat as the original message was sent.
     * 
     * @param {string|MessageMedia|Location} content 
-     * @param {?string} chatId 
-     * @param {object} options
+     * @param {string} [chatId] 
+     * @param {MessageSendOptions} [options]
     * @returns {Promise<Message>}
     */
    async reply(content, chatId, options = {}) {