feat: change say() method response type from void to Message (#1866)

* feat: change say() method response type from void to Message

* modify: bump wechaty and puppet version

* Bump wechaty and wechaty-puppet version

* 0.29.3

* modify: check void response type, remove useless await

* modify: check response type and refactory code style

* modify: check msgId more strictly.

* modify: update readme and JS doc, remove useless code.

* modify: grammar fix

README.md

@@ -191,7 +191,7 @@ All wechat contacts(friends/non-friends) will be encapsulated as a Contact.
 | static | [`load(query: string): Contact`](https://chatie.io/wechaty/#Contact.load) | get contact by id |
 | property | `id: readonly string` | get contact id |
 | method | [`sync(): Promise<void>`](https://chatie.io/wechaty/#Contact+sync) | force reload data for contact , sync data from lowlevel API again|
-| method | [`say(text: string): Promise<void>`](https://chatie.io/wechaty/#Contact+say) | send text, Contact, or file to contact |
+| method | [`say(text: string): Promise<void | Message>`](https://chatie.io/wechaty/#Contact+say) | send text, Contact, or file to contact, return the message which the bot sent (only `puppet-padplus` supported). |
 | method | [`self(): boolean`](https://chatie.io/wechaty/#Contact+self) | check if contact is self |
 | method | [`name(): string`](https://chatie.io/wechaty/#Contact+name) | get the name from a contact |
 | method | [`alias(): Promise<string>`](https://chatie.io/wechaty/#Contact+alias) | get the alias for a contact |
@@ -237,7 +237,7 @@ All wechat messages will be encapsulated as a Message.
 | method | [`to(): Contact`](https://chatie.io/wechaty/#Message+to) | get the destination of the message |
 | method | [`room(): null \| Room`](https://chatie.io/wechaty/#Message+room) | get the room from the message.(If the message is not in a room, then will return `null`) |
 | method | [`text(): string`](https://chatie.io/wechaty/#Message+text) | get the text content of the message |
-| method | [`say(text: string): Promise<void>`](https://chatie.io/wechaty/#Message+say) | reply a Text, Media File , or contact message to the sender. |
+| method | [`say(text: string): Promise<void | Message>`](https://chatie.io/wechaty/#Message+say) | reply a Text, Media File , or contact message to the sender, return the message which the bot sent (only `puppet-padplus` supported). |
 | method | [`type(): MessageType`](https://chatie.io/wechaty/#Message+type) | get the type from the message |
 | method | [`self(): boolean`](https://chatie.io/wechaty/#Message+self) | check if a message is sent by self |
 | method | [`mention(): Contact[]`](https://chatie.io/wechaty/#Message+mention) | get message mentioned contactList. |
@@ -264,7 +264,7 @@ All wechat rooms(groups) will be encapsulated as a Room.
 | event | [`leave`](https://chatie.io/wechaty/#Room+on) | emit when anyone leave the room |
 | event | [`invite`](https://chatie.io/wechaty/#Room+on) | emit when receive a room invitation |
 | method | [`sync(): <Promise<void>`](https://chatie.io/wechaty/#Room+sync) | force reload data for room, sync data from lowlevel API again.
-| method | [`say(text: string): Promise<void>`](https://chatie.io/wechaty/#Room+say) | Send text,media file, contact card, or text with mention @mention contact inside Room |
+| method | [`say(text: string): Promise<void | Message>`](https://chatie.io/wechaty/#Room+say) | Send text,media file, contact card, or text with mention @mention contact inside Room, return the message which the bot sent (only `puppet-padplus` supported). |
 | method | [`add(contact: Contact): Promise<void>`](https://chatie.io/wechaty/#Room+add) | Add contact in a room |
 | method | [`del(contact: Contact): Promise<void>`](https://chatie.io/wechaty/#Room+del) | Delete a contact from the room |
 | method | [`quit(): Promise<void>`](https://chatie.io/wechaty/#Room+quit) | Bot quit the room itself |

package.json

 {
   "name": "wechaty",
-  "version": "0.29.4",
+  "version": "0.29.5",
   "description": "Wechaty is a Bot SDK for Wechat Personal Account",
   "main": "dist/src/index.js",
   "typings": "dist/src/index.d.ts",
@@ -98,7 +98,7 @@
     "semver": "^6.0.0",
     "state-switch": "^0.6.2",
     "watchdog": "^0.8.1",
-    "wechaty-puppet": "^0.17.1",
+    "wechaty-puppet": "^0.17.2",
     "ws": "^7.0.0"
   },
   "devDependencies": {

src/types.ts

 import {
   Contact,
+  Message,
 }           from './user'
 
 export type AnyFunction = (...args: any[]) => any
@@ -8,7 +9,7 @@ export interface Sayable {
   say (
     text     : string,
     replyTo? : Contact | Contact[]
-  ): Promise<void>
+  ): Promise<void | Message>
 }
 
 export interface Acceptable {

src/user/contact.ts

@@ -41,6 +41,7 @@ import {
 
 import { UrlLink }  from './url-link'
 import { MiniProgram }  from './mini-program'
+import { Message } from './message'
 
 export const POOL = Symbol('pool')
 
@@ -298,11 +299,11 @@ export class Contact extends Accessory implements Sayable {
     return `Contact<${identity}>`
   }
 
-  public async say (text:     string)      : Promise<void>
-  public async say (contact:  Contact)     : Promise<void>
-  public async say (file:     FileBox)     : Promise<void>
-  public async say (mini:     MiniProgram) : Promise<void>
-  public async say (url:      UrlLink)     : Promise<void>
+  public async say (text:     string)      : Promise<void | Message>
+  public async say (contact:  Contact)     : Promise<void | Message>
+  public async say (file:     FileBox)     : Promise<void | Message>
+  public async say (mini:     MiniProgram) : Promise<void | Message>
+  public async say (url:      UrlLink)     : Promise<void | Message>
 
   /**
    * > Tips:
@@ -311,7 +312,7 @@ export class Contact extends Accessory implements Sayable {
    * @param {(string | Contact | FileBox | UrlLink | MiniProgram)} something
    * send text, Contact, or file to contact. </br>
    * You can use {@link https://www.npmjs.com/package/file-box|FileBox} to send file
-   * @returns {Promise<void>}
+   * @returns {Promise<void | Message>}
    * @example
    * const bot = new Wechaty()
    * await bot.start()
@@ -320,6 +321,7 @@ export class Contact extends Accessory implements Sayable {
    * // 1. send text to contact
    *
    * await contact.say('welcome to wechaty!')
+   * const msg = await contact.say('welcome to wechaty!') // only supported by puppet-padplus
    *
    * // 2. send media file to contact
    *
@@ -327,12 +329,14 @@ export class Contact extends Accessory implements Sayable {
    * const fileBox1 = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
    * const fileBox2 = FileBox.fromFile('/tmp/text.txt')
    * await contact.say(fileBox1)
+   * const msg1 = await contact.say(fileBox1) // only supported by puppet-padplus
    * await contact.say(fileBox2)
+   * const msg2 = await contact.say(fileBox2) // only supported by puppet-padplus
    *
    * // 3. send contact card to contact
    *
    * const contactCard = bot.Contact.load('contactId')
-   * await contact.say(contactCard)
+   * const msg = await contact.say(contactCard) // only supported by puppet-padplus
    *
    * // 4. send url link to contact
    *
@@ -343,6 +347,7 @@ export class Contact extends Accessory implements Sayable {
    *   url         : 'https://github.com/chatie/wechaty',
    * })
    * await contact.say(urlLink)
+   * const msg = await contact.say(urlLink) // only supported by puppet-padplus
    *
    * // 5. send mini program to contact
    *
@@ -355,6 +360,7 @@ export class Contact extends Accessory implements Sayable {
    *   thumbnailurl       : '',               //optional
    * })
    * await contact.say(miniProgram)
+   * const msg = await contact.say(miniProgram) // only supported by puppet-padplus
    */
   public async say (
     something:  string
@@ -362,47 +368,52 @@ export class Contact extends Accessory implements Sayable {
               | FileBox
               | MiniProgram
               | UrlLink
-  ): Promise<void> {
+  ): Promise<void | Message> {
     log.verbose('Contact', 'say(%s)', something)
-
+    let msgId: string | void
     if (typeof something === 'string') {
       /**
        * 1. Text
        */
-      await this.puppet.messageSendText({
+      msgId = await this.puppet.messageSendText({
         contactId: this.id,
       }, something)
     } else if (something instanceof Contact) {
       /**
        * 2. Contact
        */
-      await this.puppet.messageSendContact({
+      msgId = await this.puppet.messageSendContact({
         contactId: this.id,
       }, something.id)
     } else if (something instanceof FileBox) {
       /**
        * 3. File
        */
-      await this.puppet.messageSendFile({
+      msgId = await this.puppet.messageSendFile({
         contactId: this.id,
       }, something)
     } else if (something instanceof UrlLink) {
       /**
        * 4. Link Message
        */
-      await this.puppet.messageSendUrl({
+      msgId = await this.puppet.messageSendUrl({
         contactId : this.id,
       }, something.payload)
     } else if (something instanceof MiniProgram) {
       /**
        * 5. Mini Program
        */
-      await this.puppet.messageSendMiniProgram({
+      msgId = await this.puppet.messageSendMiniProgram({
         contactId : this.id,
       }, something.payload)
     } else {
       throw new Error('unsupported arg: ' + something)
     }
+    if (msgId) {
+      const msg = this.wechaty.Message.load(msgId)
+      await msg.ready()
+      return msg
+    }
   }
 
   /**

src/user/message.ts

@@ -422,11 +422,11 @@ export class Message extends Accessory implements Sayable {
     }
   }
 
-  public async say (text:    string, mention?: Contact | Contact[]) : Promise<void>
-  public async say (contact: Contact)                               : Promise<void>
-  public async say (file:    FileBox)                               : Promise<void>
-  public async say (url:     UrlLink)                               : Promise<void>
-  public async say (mini:    MiniProgram)                           : Promise<void>
+  public async say (text:    string, mention?: Contact | Contact[]) : Promise<void | Message>
+  public async say (contact: Contact)                               : Promise<void | Message>
+  public async say (file:    FileBox)                               : Promise<void | Message>
+  public async say (url:     UrlLink)                               : Promise<void | Message>
+  public async say (mini:    MiniProgram)                           : Promise<void | Message>
 
   public async say (...args: never[]): Promise<never>
   /**
@@ -440,7 +440,7 @@ export class Message extends Accessory implements Sayable {
    * You can use {@link https://www.npmjs.com/package/file-box|FileBox} to send file
    * @param {(Contact|Contact[])} [mention]
    * If this is a room message, when you set mention param, you can `@` Contact in the room.
-   * @returns {Promise<void>}
+   * @returns {Promise<void | Message>}
    *
    * @example
    * import { FileBox }  from 'file-box'
@@ -453,12 +453,14 @@ export class Message extends Accessory implements Sayable {
    *   if (/^ding$/i.test(m.text())) {
    *     const fileBox = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
    *     await msg.say(fileBox)
+   *     const message = await msg.say(fileBox) // only supported by puppet-padplus
    *   }
    *
    * // 2. send Text
    *
    *   if (/^dong$/i.test(m.text())) {
    *     await msg.say('dingdingding')
+   *     const message = await msg.say('dingdingding') // only supported by puppet-padplus
    *   }
    *
    * // 3. send Contact
@@ -470,6 +472,7 @@ export class Message extends Accessory implements Sayable {
    *       return
    *     }
    *     await msg.say(contactCard)
+   *     const message = await msg.say(contactCard) // only supported by puppet-padplus
    *   }
    *
    * // 4. send Link
@@ -482,6 +485,7 @@ export class Message extends Accessory implements Sayable {
    *       url         : 'https://github.com/chatie/wechaty',
    *     })
    *     await msg.say(linkPayload)
+   *     const message = await msg.say(linkPayload) // only supported by puppet-padplus
    *   }
    *
    * // 5. send MiniProgram
@@ -496,6 +500,7 @@ export class Message extends Accessory implements Sayable {
    *       thumbnailurl       : '',               //optional
    *     })
    *     await msg.say(miniProgramPayload)
+   *     const message = await msg.say(miniProgramPayload) // only supported by puppet-padplus
    *   }
    *
    * })
@@ -503,19 +508,19 @@ export class Message extends Accessory implements Sayable {
    */
   public async say (
     textOrContactOrFileOrUrlOrMini : string | Contact | FileBox | UrlLink | MiniProgram,
-  ): Promise<void> {
+  ): Promise<void | Message> {
     log.verbose('Message', 'say(%s)', textOrContactOrFileOrUrlOrMini)
 
     // const user = this.puppet.userSelf()
     const from = this.from()
     // const to   = this.to()
     const room = this.room()
-
+    let msgId: void | string
     if (typeof textOrContactOrFileOrUrlOrMini === 'string') {
       /**
        * Text Message
        */
-      await this.puppet.messageSendText({
+      msgId = await this.puppet.messageSendText({
         contactId : (from && from.id) || undefined,
         roomId    : (room && room.id) || undefined,
       }, textOrContactOrFileOrUrlOrMini)
@@ -523,7 +528,7 @@ export class Message extends Accessory implements Sayable {
       /**
        * Contact Card
        */
-      await this.puppet.messageSendContact({
+      msgId = await this.puppet.messageSendContact({
         contactId : (from && from.id) || undefined,
         roomId    : (room && room.id) || undefined,
       }, textOrContactOrFileOrUrlOrMini.id)
@@ -531,7 +536,7 @@ export class Message extends Accessory implements Sayable {
       /**
        * File Message
        */
-      await this.puppet.messageSendFile({
+      msgId = await this.puppet.messageSendFile({
         contactId : (from && from.id) || undefined,
         roomId    : (room && room.id) || undefined,
       }, textOrContactOrFileOrUrlOrMini)
@@ -539,7 +544,7 @@ export class Message extends Accessory implements Sayable {
       /**
        * Link Message
        */
-      await this.puppet.messageSendUrl({
+      msgId = await this.puppet.messageSendUrl({
         contactId : (from && from.id) || undefined,
         roomId    : (room && room.id) || undefined,
       }, textOrContactOrFileOrUrlOrMini.payload)
@@ -547,13 +552,18 @@ export class Message extends Accessory implements Sayable {
       /**
        * MiniProgram
        */
-      await this.puppet.messageSendMiniProgram({
+      msgId = await this.puppet.messageSendMiniProgram({
         contactId : (from && from.id) || undefined,
         roomId    : (room && room.id) || undefined,
       }, textOrContactOrFileOrUrlOrMini.payload)
     } else {
       throw new Error('unknown msg: ' + textOrContactOrFileOrUrlOrMini)
     }
+    if (msgId) {
+      const msg = this.wechaty.Message.load(msgId)
+      await msg.ready()
+      return msg
+    }
   }
 
   /**

src/user/room.ts

@@ -47,6 +47,7 @@ import {
   RoomPayload,
   RoomQueryFilter,
 }                         from 'wechaty-puppet'
+import { Message } from './message'
 
 export const ROOM_EVENT_DICT = {
   invite: 'tbw',
@@ -374,12 +375,12 @@ export class Room extends Accessory implements Sayable {
     return !!(this.payload)
   }
 
-  public say (text:     string)                                          : Promise<void>
-  public say (text:     string, ...mentionList: Contact[])               : Promise<void>
-  public say (textList: TemplateStringsArray, ...mentionList: Contact[]) : Promise<void>
-  public say (file:     FileBox)                                         : Promise<void>
-  public say (url:      UrlLink)                                         : Promise<void>
-  public say (mini:     MiniProgram)                                     : Promise<void>
+  public say (text:     string)                                          : Promise<void | Message>
+  public say (text:     string, ...mentionList: Contact[])               : Promise<void | Message>
+  public say (textList: TemplateStringsArray, ...mentionList: Contact[]) : Promise<void | Message>
+  public say (file:     FileBox)                                         : Promise<void | Message>
+  public say (url:      UrlLink)                                         : Promise<void | Message>
+  public say (mini:     MiniProgram)                                     : Promise<void | Message>
 
   public say (...args: never[]): never
 
@@ -391,7 +392,7 @@ export class Room extends Accessory implements Sayable {
    * @param {(string | Contact | FileBox)} textOrContactOrFileOrUrlOrMini - Send `text` or `media file` inside Room. <br>
    * You can use {@link https://www.npmjs.com/package/file-box|FileBox} to send file
    * @param {(Contact | Contact[])} [mention] - Optional parameter, send content inside Room, and mention @replyTo contact or contactList.
-   * @returns {Promise<void>}
+   * @returns {Promise<void | Message>}
    *
    * @example
    * const bot = new Wechaty()
@@ -402,25 +403,31 @@ export class Room extends Accessory implements Sayable {
    * // 1. Send text inside Room
    *
    * await room.say('Hello world!')
+   * const msg = await room.say('Hello world!') // only supported by puppet-padplus
    *
    * // 2. Send media file inside Room
    * import { FileBox }  from 'file-box'
    * const fileBox1 = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
    * const fileBox2 = FileBox.fromLocal('/tmp/text.txt')
    * await room.say(fileBox1)
+   * const msg1 = await room.say(fileBox1) // only supported by puppet-padplus
    * await room.say(fileBox2)
+   * const msg2 = await room.say(fileBox2) // only supported by puppet-padplus
    *
    * // 3. Send Contact Card in a room
    * const contactCard = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of the room member
    * await room.say(contactCard)
+   * const msg = await room.say(contactCard) // only supported by puppet-padplus
    *
    * // 4. Send text inside room and mention @mention contact
    * const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of the room member
    * await room.say('Hello world!', contact)
+   * const msg = await room.say('Hello world!', contact) // only supported by puppet-padplus
    *
    * // 5. Send text inside room and mention someone with Tagged Template
    * const contact2 = await bot.Contact.find({name: 'zixia'}) // change 'zixia' to any of the room member
    * await room.say`Hello ${contact}, here is the world ${contact2}`
+   * const msg = await room.say`Hello ${contact}, here is the world ${contact2}` // only supported by puppet-padplus
    *
    * // 6. send url link in a room
    *
@@ -431,6 +438,7 @@ export class Room extends Accessory implements Sayable {
    *   url         : 'https://github.com/chatie/wechaty',
    * })
    * await room.say(urlLink)
+   * const msg = await room.say(urlLink) // only supported by puppet-padplus
    *
    * // 7. send mini program in a room
    *
@@ -443,6 +451,7 @@ export class Room extends Accessory implements Sayable {
    *   thumbnailurl       : '',               //optional
    * })
    * await room.say(miniProgram)
+   * const msg = await room.say(miniProgram) // only supported by puppet-padplus
    */
   public async say (
     something : string
@@ -452,7 +461,7 @@ export class Room extends Accessory implements Sayable {
               | TemplateStringsArray
               | UrlLink,
     ...mentionList : Contact[]
-  ): Promise<void> {
+  ): Promise<void | Message> {
 
     log.verbose('Room', 'say(%s, %s)',
       something,
@@ -460,7 +469,7 @@ export class Room extends Accessory implements Sayable {
     )
 
     let text: string
-
+    let msgId: string | void
     if (typeof something === 'string') {
 
       if (mentionList.length > 0) {
@@ -478,7 +487,7 @@ export class Room extends Accessory implements Sayable {
         contactId : (mentionList.length && mentionList[0].id) || undefined,
         roomId    : this.id,
       }
-      await this.puppet.messageSendText(
+      msgId = await this.puppet.messageSendText(
         receiver,
         text,
         mentionList.map(c => c.id),
@@ -487,38 +496,43 @@ export class Room extends Accessory implements Sayable {
       /**
        * 2. File Message
        */
-      await this.puppet.messageSendFile({
+      msgId = await this.puppet.messageSendFile({
         roomId: this.id,
       }, something)
     } else if (something instanceof Contact) {
       /**
        * 3. Contact Card
        */
-      await this.puppet.messageSendContact({
+      msgId = await this.puppet.messageSendContact({
         roomId: this.id,
       }, something.id)
     } else if (something instanceof UrlLink) {
       /**
        * 4. Link Message
        */
-      await this.puppet.messageSendUrl({
+      msgId = await this.puppet.messageSendUrl({
         contactId : this.id,
       }, something.payload)
     } else if (something instanceof MiniProgram) {
       /**
        * 5. Mini Program
        */
-      await this.puppet.messageSendMiniProgram({
+      msgId = await this.puppet.messageSendMiniProgram({
         contactId : this.id,
       }, something.payload)
     } else if (something instanceof Array) {
-      await this.sayTemplateStringsArray(
+      msgId = await this.sayTemplateStringsArray(
         something,
         ...mentionList,
       )
     } else {
       throw new Error('arg unsupported: ' + something)
     }
+    if (msgId) {
+      const msg = this.wechaty.Message.load(msgId)
+      await msg.ready()
+      return msg
+    }
   }
 
   private async sayTemplateStringsArray (
@@ -533,7 +547,7 @@ export class Room extends Accessory implements Sayable {
       /**
        * No mention in the string
        */
-      await this.puppet.messageSendText(
+      return this.puppet.messageSendText(
         receiver,
         textList[0],
       )
@@ -541,7 +555,7 @@ export class Room extends Accessory implements Sayable {
       /**
        * Constructed mention string, skip inserting @ signs
        */
-      await this.puppet.messageSendText(
+      return this.puppet.messageSendText(
         receiver,
         textList[0],
         mentionList.map(c => c.id),
@@ -561,7 +575,7 @@ export class Room extends Accessory implements Sayable {
         constructedString += textList[i] + '@' + (await this.alias(mentionList[i]) || mentionList[i].name())
       }
       constructedString += textList[i]
-      await this.puppet.messageSendText(
+      return this.puppet.messageSendText(
         receiver,
         constructedString,
         mentionList.map(c => c.id),