diff --git a/docs/index.md b/docs/index.md index 0e03a9896b5195abe51bd4ace67b6e956db4ab59..fe87a1b8ccf92bfc29446fdc0a8d8305453a6c0b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# Wechaty v0.29.21 Documentation +# Wechaty v0.37.4 Documentation - Blog - - Docs - @@ -117,6 +117,7 @@ See more: * [Wechaty](#Wechaty) * [new Wechaty([options])](#new_Wechaty_new) * _instance_ + * [.name()](#Wechaty+name) * [.on(event, listener)](#Wechaty+on) ⇒ [Wechaty](#Wechaty) * [.start()](#Wechaty+start) ⇒ Promise.<void> * [.stop()](#Wechaty+stop) ⇒ Promise.<void> @@ -146,6 +147,13 @@ bot.on('login', user => console.log(`User ${user} logined`)) bot.on('message', message => console.log(`Message: ${message}`)) bot.start() ``` + + +### wechaty.name() +Wechaty bot name set by `optoins.name` +default: `wechaty` + +**Kind**: instance method of [Wechaty](#Wechaty) ### wechaty.on(event, listener) ⇒ [Wechaty](#Wechaty) @@ -431,6 +439,7 @@ All wechat rooms(groups) will be encapsulated as a Room. * [.memberAll([query])](#Room+memberAll) ⇒ Promise.<Array.<Contact>> * [.member(queryArg)](#Room+member) ⇒ Promise.<(null\|Contact)> * [.owner()](#Room+owner) ⇒ [Contact](#Contact) \| null + * [.avatar()](#Room+avatar) ⇒ FileBox * _static_ * [.create(contactList, [topic])](#Room.create) ⇒ [Promise.<Room>](#Room) * [.findAll([query])](#Room.findAll) ⇒ Promise.<Array.<Room>> @@ -557,6 +566,18 @@ if (room) { }) } ``` +**Example** *(Event:message )* +```js +const bot = new Wechaty() +await bot.start() +// after logged in... +const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your wechat +if (room) { + room.on('message', (message) => { + console.log(`Room received new message: ${message}`) + }) +} +``` **Example** *(Event:topic )* ```js const bot = new Wechaty() @@ -865,6 +886,18 @@ This function is depending on the Puppet Implementation, see [puppet-compatible- ```js const owner = room.owner() ``` + + +### room.avatar() ⇒ FileBox +Get avatar from the room. + +**Kind**: instance method of [Room](#Room) +**Example** +```js +const fileBox = await room.avatar() +const name = fileBox.name +fileBox.toFile(name) +``` ### Room.create(contactList, [topic]) ⇒ [Promise.<Room>](#Room) @@ -952,11 +985,13 @@ All wechat contacts(friend) will be encapsulated as a Contact. * [.province()](#Contact+province) ⇒ string \| null * [.city()](#Contact+city) ⇒ string \| null * [.avatar()](#Contact+avatar) ⇒ Promise.<FileBox> + * [.tags()](#Contact+tags) ⇒ Promise.<Array.<Tag>> * [.sync()](#Contact+sync) ⇒ Promise.<this> * [.self()](#Contact+self) ⇒ boolean * _static_ * [.find(query)](#Contact.find) ⇒ Promise.<(Contact\|null)> * [.findAll([queryArg])](#Contact.findAll) ⇒ Promise.<Array.<Contact>> + * [.tags()](#Contact.tags) ⇒ Promise.<Array.<Tag>> @@ -1145,6 +1180,16 @@ const name = file.name await file.toFile(name, true) console.log(`Contact: ${contact.name()} with avatar file: ${name}`) ``` + + +### contact.tags() ⇒ Promise.<Array.<Tag>> +Get all tags of contact + +**Kind**: instance method of [Contact](#Contact) +**Example** +```js +const tags = await contact.tags() +``` ### contact.sync() ⇒ Promise.<this> @@ -1212,6 +1257,16 @@ const contactList = await bot.Contact.findAll() // get the const contactList = await bot.Contact.findAll({ name: 'ruirui' }) // find allof the contacts whose name is 'ruirui' const contactList = await bot.Contact.findAll({ alias: 'lijiarui' }) // find all of the contacts whose alias is 'lijiarui' ``` + + +### Contact.tags() ⇒ Promise.<Array.<Tag>> +Get tags for all contact + +**Kind**: static method of [Contact](#Contact) +**Example** +```js +const tags = await wechaty.Contact.tags() +``` ## ContactSelf @@ -1316,9 +1371,12 @@ Send, receive friend request, and friend confirmation events. * [.hello()](#Friendship+hello) ⇒ string * [.contact()](#Friendship+contact) ⇒ [Contact](#Contact) * [.type()](#Friendship+type) ⇒ FriendshipType + * [.toJSON()](#Friendship+toJSON) ⇒ FriendshipPayload * _static_ + * [.search(condition)](#Friendship.search) ⇒ [Promise.<Contact>](#Contact) * ~~[.send()](#Friendship.send)~~ * [.add(contact, hello)](#Friendship.add) ⇒ Promise.<void> + * [.fromJSON()](#Friendship.fromJSON) @@ -1414,6 +1472,47 @@ bot.on('friendship', async friendship => { } .start() ``` + + +### friendship.toJSON() ⇒ FriendshipPayload +get friendShipPayload Json + +**Kind**: instance method of [Friendship](#Friendship) +**Example** +```js +const bot = new Wechaty() +bot.on('friendship', async friendship => { + try { + // JSON.stringify(friendship) as well. + const payload = await friendship.toJSON() + } catch (e) { + console.error(e) + } +} +.start() +``` + + +### Friendship.search(condition) ⇒ [Promise.<Contact>](#Contact) +Search a Friend by phone or weixin. + +The best practice is to search friend request once per minute. +Remeber not to do this too frequently, or your account may be blocked. + +**Kind**: static method of [Friendship](#Friendship) + +| Param | Type | Description | +| --- | --- | --- | +| condition | FriendshipSearchCondition | Search friend by phone or weixin. | + +**Example** +```js +const friend_phone = await bot.Friendship.search({phone: '13112341234'}) +const friend_weixin = await bot.Friendship.search({weixin: 'weixin_account'}) + +console.log(`This is the new friend info searched by phone : ${friend_phone}`) +await bot.Friendship.add(friend_phone, 'hello') +``` ### ~~Friendship.send()~~ @@ -1444,6 +1543,21 @@ for (let i = 0; i < memberList.length; i++) { await bot.Friendship.add(member, 'Nice to meet you! I am wechaty bot!') } ``` + + +### Friendship.fromJSON() +create friendShip by friendshipJson + +**Kind**: static method of [Friendship](#Friendship) +**Example** +```js +const bot = new Wechaty() +bot.start() + +const payload = '{...}' // your saved JSON payload +const friendship = bot.FriendShip.fromJSON(friendshipFromDisk) +await friendship.accept() +``` ## Message @@ -1462,6 +1576,7 @@ All wechat messages will be encapsulated as a Message. * [.text()](#Message+text) ⇒ string * [.toRecalled()](#Message+toRecalled) * [.say(textOrContactOrFile, [mention])](#Message+say) ⇒ Promise.<(void\|Message)> + * [.recall()](#Message+recall) ⇒ Promise.<boolean> * [.type()](#Message+type) ⇒ MessageType * [.self()](#Message+self) ⇒ boolean * [.mentionList()](#Message+mentionList) ⇒ Promise.<Array.<Contact>> @@ -1471,6 +1586,7 @@ All wechat messages will be encapsulated as a Message. * [.age()](#Message+age) ⇒ number * ~~[.file()](#Message+file)~~ * [.toFileBox()](#Message+toFileBox) ⇒ Promise.<FileBox> + * [.toImage()](#Message+toImage) ⇒ Image * [.toContact()](#Message+toContact) ⇒ [Promise.<Contact>](#Contact) * _static_ * [.find()](#Message.find) @@ -1659,6 +1775,24 @@ bot }) .start() ``` + + +### message.recall() ⇒ Promise.<boolean> +Recall a message. +> Tips: + +**Kind**: instance method of [Message](#Message) +**Example** +```js +const bot = new Wechaty() +bot +.on('message', async m => { + const recallMessage = await msg.say('123') + if (recallMessage) { + const isSuccess = await recallMessage.recall() + } +}) +``` ### message.type() ⇒ MessageType @@ -1791,6 +1925,21 @@ const fileBox = await message.toFileBox() const fileName = fileBox.name fileBox.toFile(fileName) ``` + + +### message.toImage() ⇒ Image +Extract the Image File from the Message, so that we can use different image sizes. +> Tips: +This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table) + +**Kind**: instance method of [Message](#Message) +**Example** *(Save image file from a message)* +```js +const image = message.toImage() +const fileBox = await image.artwork() +const fileName = fileBox.name +fileBox.toFile(fileName) +``` ### message.toContact() ⇒ [Promise.<Contact>](#Contact) @@ -1820,12 +1969,15 @@ accept room invitation **Kind**: global class * [RoomInvitation](#RoomInvitation) - * [.accept()](#RoomInvitation+accept) ⇒ Promise.<void> - * [.inviter()](#RoomInvitation+inviter) ⇒ [Contact](#Contact) - * [.topic()](#RoomInvitation+topic) ⇒ [Contact](#Contact) - * [.roomTopic()](#RoomInvitation+roomTopic) - * [.date()](#RoomInvitation+date) ⇒ Promise.<Date> - * [.age()](#RoomInvitation+age) ⇒ number + * _instance_ + * [.accept()](#RoomInvitation+accept) ⇒ Promise.<void> + * [.inviter()](#RoomInvitation+inviter) ⇒ [Contact](#Contact) + * [.topic()](#RoomInvitation+topic) ⇒ [Contact](#Contact) + * [.date()](#RoomInvitation+date) ⇒ Promise.<Date> + * [.age()](#RoomInvitation+age) ⇒ number + * [.toJSON()](#RoomInvitation+toJSON) ⇒ string + * _static_ + * [.fromJSON()](#RoomInvitation.fromJSON) ⇒ [RoomInvitation](#RoomInvitation) @@ -1877,11 +2029,6 @@ bot.on('room-invite', async roomInvitation => { } .start() ``` - - -### roomInvitation.roomTopic() -**Kind**: instance method of [RoomInvitation](#RoomInvitation) -**Deprecated:**: use topic() instead ### roomInvitation.date() ⇒ Promise.<Date> @@ -1898,6 +2045,35 @@ and when we received it in Wechaty, the time is `8:43:15`, then the age() will return `8:43:15 - 8:43:01 = 14 (seconds)` **Kind**: instance method of [RoomInvitation](#RoomInvitation) + + +### roomInvitation.toJSON() ⇒ string +Get the room invitation info when listened on room-invite event + +**Kind**: instance method of [RoomInvitation](#RoomInvitation) +**Example** +```js +const bot = new Wechaty() +bot.on('room-invite', async roomInvitation => { + const roomInvitation = bot.RoomInvitation.load(roomInvitation.id) + const jsonData = await roomInvitation.toJSON(roomInvitation.id) + // save the json data to disk, and we can use it by RoomInvitation.fromJSON() +} +.start() +``` + + +### RoomInvitation.fromJSON() ⇒ [RoomInvitation](#RoomInvitation) +Load the room invitation info from disk + +**Kind**: static method of [RoomInvitation](#RoomInvitation) +**Example** +```js +const bot = new Wechaty() +const dataFromDisk // get the room invitation info data from disk +const roomInvitation = await bot.RoomInvitation.fromJSON(dataFromDisk) +await roomInvitation.accept() +``` ## PuppetModuleName