cheveguerra/whatsapp-web.js
1
0
Fork 0
mirror of https://github.com/cheveguerra/whatsapp-web.js.git synced 2026-04-19 03:59:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
stefanfuchs
2020-08-03 03:52:37 -03:00
committed by GitHub
parent bfea74f567
commit 5c84a1651d
4 changed files with 124 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
index.d.ts vendored
View File

@@ -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,

81
src/Client.js
View File

@@ -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
@@ -53,7 +67,7 @@ class Client extends EventEmitter {
this.pupBrowser = browser;
this.pupPage = page;
if (this.options.session) {
await page.evaluateOnNewDocument(
session => {
@@ -69,7 +83,7 @@ class Client extends EventEmitter {
waitUntil: 'load',
timeout: 0,
});
const KEEP_PHONE_CONNECTED_IMG_SELECTOR = '[data-asset-intro-image-light="true"]';
if (this.options.session) {
@@ -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();
}));
@@ -193,7 +215,7 @@ class Client extends EventEmitter {
}
return;
}
const message = new Message(this, msg);
/**
@@ -262,7 +284,7 @@ class Client extends EventEmitter {
await page.exposeFunction('onMessageAckEvent', (msg, ack) => {
const message = new Message(this, msg);
/**
* Emitted when an ack event occurrs on message type.
* @event Client#message_ack
@@ -276,7 +298,7 @@ class Client extends EventEmitter {
await page.exposeFunction('onMessageMediaUploadedEvent', (msg) => {
const message = new Message(this, msg);
/**
* Emitted when media has been uploaded for a message sent by the client.
* @event Client#media_uploaded
@@ -296,10 +318,10 @@ class Client extends EventEmitter {
const ACCEPTED_STATES = [WAState.CONNECTED, WAState.OPENING, WAState.PAIRING, WAState.TIMEOUT];
if(this.options.takeoverOnConflict) {
if (this.options.takeoverOnConflict) {
ACCEPTED_STATES.push(WAState.CONFLICT);
if(state === WAState.CONFLICT) {
if (state === WAState.CONFLICT) {
setTimeout(() => {
this.pupPage.evaluate(() => window.Store.AppState.takeover());
}, this.options.takeoverTimeoutMs);
@@ -320,7 +342,7 @@ class Client extends EventEmitter {
await page.exposeFunction('onBatteryStateChangedEvent', (state) => {
const { battery, plugged } = state;
if(battery === undefined) return;
if (battery === undefined) return;
/**
* Emitted when the battery percentage for the attached device changes
@@ -333,12 +355,12 @@ class Client extends EventEmitter {
});
await page.evaluate(() => {
window.Store.Msg.on('add', (msg) => { if(msg.isNewMsg) window.onAddMessageEvent(msg); });
window.Store.Msg.on('add', (msg) => { if (msg.isNewMsg) window.onAddMessageEvent(msg); });
window.Store.Msg.on('change', (msg) => { window.onChangeMessageEvent(msg); });
window.Store.Msg.on('change:type', (msg) => { window.onChangeMessageTypeEvent(msg); });
window.Store.Msg.on('change:ack', (msg, ack) => { window.onMessageAckEvent(msg, ack); });
window.Store.Msg.on('change:isUnsentMedia', (msg, unsent) => { if(msg.id.fromMe && !unsent) window.onMessageMediaUploadedEvent(msg); });
window.Store.Msg.on('remove', (msg) => { if(msg.isNewMsg) window.onRemoveMessageEvent(msg); });
window.Store.Msg.on('change:isUnsentMedia', (msg, unsent) => { if (msg.id.fromMe && !unsent) window.onMessageMediaUploadedEvent(msg); });
window.Store.Msg.on('remove', (msg) => { if (msg.isNewMsg) window.onRemoveMessageEvent(msg); });
window.Store.AppState.on('change:state', (_AppState, state) => { window.onAppStateChangedEvent(state); });
window.Store.Conn.on('change:battery', (state) => { window.onBatteryStateChangedEvent(state); });
});
@@ -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 = {}) {
@@ -408,7 +443,7 @@ class Client extends EventEmitter {
quotedMessageId: options.quotedMessageId,
mentionedJidList: Array.isArray(options.mentions) ? options.mentions.map(contact => contact.id._serialized) : []
};
const sendSeen = typeof options.sendSeen === 'undefined' ? true : options.sendSeen;
if (content instanceof MessageMedia) {
@@ -427,7 +462,7 @@ class Client extends EventEmitter {
const chatWid = window.Store.WidFactory.createWid(chatId);
const chat = await window.Store.Chat.find(chatWid);
if(sendSeen) {
if (sendSeen) {
window.WWebJS.sendSeen(chatId);
}
@@ -575,7 +610,7 @@ class Client extends EventEmitter {
await chat.mute.mute(timestamp, !0);
}, chatId, unmuteDate.getTime() / 1000);
}
/**
* Unmutes the Chat
* @param {string} chatId ID of the chat that will be unmuted
@@ -586,7 +621,7 @@ class Client extends EventEmitter {
await window.Store.Cmd.muteChat(chat, false);
}, chatId);
}
/**
* Returns the contact ID's profile picture URL, if privacy settings allow it
* @param {string} contactId the whatsapp user's ID
@@ -603,7 +638,7 @@ class Client extends EventEmitter {
/**
* Force reset of connection state for the client
*/
async resetState(){
async resetState() {
await this.pupPage.evaluate(() => {
window.Store.AppState.phoneWatchdog.shiftTimer.forceRunNow();
});
@@ -630,18 +665,18 @@ class Client extends EventEmitter {
* @returns {Object.<string,string>} createRes.missingParticipants - participants that were not added to the group. Keys represent the ID for participant that was not added and its value is a status code that represents the reason why participant could not be added. This is usually 403 if the user's privacy settings don't allow you to add them to groups.
*/
async createGroup(name, participants) {
if(!Array.isArray(participants) || participants.length == 0) {
if (!Array.isArray(participants) || participants.length == 0) {
throw 'You need to add at least one other participant to the group';
}
if(participants.every(c => c instanceof Contact)) {
if (participants.every(c => c instanceof Contact)) {
participants = participants.map(c => c.id._serialized);
}
const createRes = await this.pupPage.evaluate(async (name, participantIds) => {
const res = await window.Store.Wap.createGroup(name, participantIds);
console.log(res);
if(!res.status === 200) {
if (!res.status === 200) {
throw 'An error occurred while creating the group!';
}
@@ -651,11 +686,11 @@ class Client extends EventEmitter {
const missingParticipants = createRes.participants.reduce(((missing, c) => {
const id = Object.keys(c)[0];
const statusCode = c[id].code;
if(statusCode != 200) return Object.assign(missing, {[id]: statusCode});
if (statusCode != 200) return Object.assign(missing, { [id]: statusCode });
return missing;
}), {});
return { gid: createRes.gid, missingParticipants};
return { gid: createRes.gid, missingParticipants };
}
}

22
src/structures/Chat.js
View File

@@ -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) {
@@ -119,7 +119,7 @@ class Chat extends Base {
async mute(unmuteDate) {
return this.client.muteChat(this.id._serialized, unmuteDate);
}
/**
* Unmutes this chat
*/
@@ -134,18 +134,18 @@ class Chat extends Base {
* @returns {Promise<Array<Message>>}
*/
async fetchMessages(searchOptions) {
if(!searchOptions || !searchOptions.limit) {
searchOptions = {limit: 50};
if (!searchOptions || !searchOptions.limit) {
searchOptions = { limit: 50 };
}
let messages = await this.client.pupPage.evaluate(async (chatId, limit) => {
const msgFilter = m => !m.isNotification; // dont include notification messages
const chat = window.Store.Chat.get(chatId);
let msgs = chat.msgs.models.filter(msgFilter);
while(msgs.length < limit) {
while (msgs.length < limit) {
const loadedMessages = await chat.loadEarlierMsgs();
if(!loadedMessages) break;
if (!loadedMessages) break;
msgs = [...loadedMessages.filter(msgFilter), ...msgs];
}
@@ -156,7 +156,7 @@ class Chat extends Base {
return messages.map(m => new Message(this.client, m));
}
/**
* Simulate typing in chat. This will last for 25 seconds.
*/
@@ -166,7 +166,7 @@ class Chat extends Base {
return true;
}, this.id._serialized);
}
/**
* Simulate recording audio in chat. This will last for 25 seconds.
*/
@@ -176,7 +176,7 @@ class Chat extends Base {
return true;
}, this.id._serialized);
}
/**
* Stops typing or recording in chat immediately.
*/

28
src/structures/Message.js
View File

@@ -13,7 +13,7 @@ class Message extends Base {
constructor(client, data) {
super(client);
if(data) this._patch(data);
if (data) this._patch(data);
}
_patch(data) {
@@ -98,7 +98,7 @@ class Message extends Base {
* @type {boolean}
*/
this.fromMe = data.id.fromMe;
/**
* Indicates if the message was sent as a reply to another message.
* @type {boolean}
@@ -173,11 +173,11 @@ 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={}) {
async reply(content, chatId, options = {}) {
if (!chatId) {
chatId = this._getChatId();
}
@@ -201,13 +201,13 @@ class Message extends Base {
const result = await this.client.pupPage.evaluate(async (msgId) => {
const msg = window.Store.Msg.get(msgId);
if(msg.mediaData.mediaStage != 'RESOLVED') {
if (msg.mediaData.mediaStage != 'RESOLVED') {
// try to resolve media
await msg.downloadMedia(true, 1);
}
if(msg.mediaData.mediaStage.includes('ERROR')) {
if (msg.mediaData.mediaStage.includes('ERROR')) {
// media could not be downloaded
return undefined;
}
@@ -215,7 +215,7 @@ class Message extends Base {
const buffer = await window.WWebJS.downloadBuffer(msg.clientUrl);
const decrypted = await window.Store.CryptoLib.decryptE2EMedia(msg.type, buffer, msg.mediaKey, msg.mimetype);
const data = await window.WWebJS.readBlobAsync(decrypted._blob);
return {
data: data.split(',')[1],
mimetype: msg.mimetype,
@@ -224,7 +224,7 @@ class Message extends Base {
}, this.id._serialized);
if(!result) return undefined;
if (!result) return undefined;
return new MessageMedia(result.mimetype, result.data, result.filename);
}
@@ -236,10 +236,10 @@ class Message extends Base {
await this.client.pupPage.evaluate((msgId, everyone) => {
let msg = window.Store.Msg.get(msgId);
if(everyone && msg.id.fromMe && msg.canRevoke()) {
if (everyone && msg.id.fromMe && msg.canRevoke()) {
return window.Store.Cmd.sendRevokeMsgs(msg.chat, [msg], true);
}
}
return window.Store.Cmd.sendDeleteMsgs(msg.chat, [msg], true);
}, this.id._serialized, everyone);
}