merge

README.md

@@ -8,6 +8,7 @@ Wechaty is a Bot SDK for Wechat **Personal** Account which can help you create a
 
 [![NPM Version](https://badge.fury.io/js/wechaty.svg)](https://badge.fury.io/js/wechaty)
 [![Downloads](https://img.shields.io/npm/dm/wechaty.svg?style=flat-square)](https://www.npmjs.com/package/wechaty)
+[![GitHub stars](https://img.shields.io/github/stars/Chatie/wechaty.svg?label=github%20stars)](https://github.com/chatie/wechaty)
 [![Docker Pulls](https://img.shields.io/docker/pulls/zixia/wechaty.svg?maxAge=2592000)](https://hub.docker.com/r/zixia/wechaty/)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-blue.svg)](https://www.typescriptlang.org/)
 [![Greenkeeper badge](https://badges.greenkeeper.io/Chatie/wechaty.svg)](https://greenkeeper.io/)

package.json

 {
   "name": "wechaty",
-  "version": "0.19.115",
+  "version": "0.19.122",
   "description": "Wechaty is a Bot SDK for Wechat Personal Account",
   "main": "dist/src/index.js",
   "typings": "dist/src/index.d.ts",
@@ -78,9 +78,9 @@
     "brolog": "^1.8.1",
     "clone-class": "^0.6.11",
     "cuid": "^2.1.1",
-    "file-box": "^0.8.22",
+    "file-box": "^0.8.23",
     "hot-import": "^0.2.1",
-    "memory-card": "^0.4.9",
+    "memory-card": "^0.4.10",
     "npm-programmatic": "0.0.11",
     "pkg-dir": "^3.0.0",
     "promise-retry": "^1.1.1",
@@ -128,7 +128,7 @@
     "gl-matrix": "^2.6.1",
     "glob": "^7.1.0",
     "jsdoc-to-markdown": "^4.0.0",
-    "markdownlint-cli": "^0.11.0",
+    "markdownlint-cli": "^0.12.0",
     "nyc": "^12.0.1",
     "qrcode-terminal": "^0.12.0",
     "request": "^2.87.0",
@@ -141,7 +141,7 @@
     "tslint-config-standard": "^7.0.0",
     "tuling123-client": "^0.0.2",
     "typedoc": "^0.11.1",
-    "typescript": "^2.9.2",
+    "typescript": "^3.1.0-dev.20180731",
     "wechaty-puppet-mock": "^0.8.1"
   },
   "files_comment__whitelist_npm_publish": "http://stackoverflow.com/a/8617868/1123955",

scripts/generate-docs.sh

@@ -10,5 +10,5 @@ else
   echo "Generating docs ..."
   npm run dist
   echo -e '# Wechaty v'$(jq -r .version package.json)' Documentation\n\n* <https://blog.chatie.io>\n\n' > docs/index.md
-  jsdoc2md dist/src/wechaty.js dist/src/user/{room,contact,contact-self,friendship,message}.js >> docs/index.md
+  jsdoc2md dist/src/wechaty.js dist/src/user/{room,contact,contact-self,friendship,message,room-invitation}.js >> docs/index.md
 fi

src/user/contact.ts

@@ -291,7 +291,7 @@ export class Contact extends Accessory implements Sayable {
   }
 
   /**
-   * @hidden
+   * @private
    */
   public toString (): string {
     if (!this.payload) {
@@ -422,15 +422,24 @@ export class Contact extends Accessory implements Sayable {
                               : newAlias,
                 )
 
+    if (!this.payload) {
+      throw new Error('no payload')
+    }
+
     if (typeof newAlias === 'undefined') {
-      if (!this.payload) {
-        throw new Error('no payload')
-      }
       return this.payload.alias || null
     }
 
     try {
       await this.puppet.contactAlias(this.id, newAlias)
+      await this.puppet.contactPayloadDirty(this.id)
+      this.payload = await this.puppet.contactPayload(this.id)
+      if (newAlias && newAlias !== this.payload.alias) {
+        log.warn('Contact', 'alias(%s) sync with server fail: set(%s) is not equal to get(%s)',
+                            newAlias,
+                            this.payload.alias,
+                )
+      }
     } catch (e) {
       log.error('Contact', 'alias(%s) rejected: %s', newAlias, e.message)
       Raven.captureException(e)
@@ -443,6 +452,7 @@ export class Contact extends Accessory implements Sayable {
    * Should use {@link Contact#friend} instead
    *
    * @deprecated
+   * @private
    */
   public stranger (): null | boolean {
     log.warn('Contact', 'stranger() DEPRECATED. use friend() instead.')
@@ -480,7 +490,7 @@ export class Contact extends Accessory implements Sayable {
    * @description
    * Check if it's a offical account, should use {@link Contact#type} instead
    * @deprecated
-   *
+   * @private
    */
   public official (): boolean {
     log.warn('Contact', 'official() DEPRECATED. use type() instead')
@@ -491,6 +501,7 @@ export class Contact extends Accessory implements Sayable {
    * @description
    * Check if it's a personal account, should use {@link Contact#type} instead
    * @deprecated
+   * @private
    */
   public personal (): boolean {
     log.warn('Contact', 'personal() DEPRECATED. use type() instead')
@@ -605,6 +616,7 @@ export class Contact extends Accessory implements Sayable {
    * Force reload(re-ready()) data for Contact, use {@link Contact#sync} instead
    *
    * @deprecated
+   * @private
    */
   public refresh (): Promise<void> {
     log.warn('Contact', 'refresh() DEPRECATED. use sync() instead.')
@@ -617,6 +629,7 @@ export class Contact extends Accessory implements Sayable {
    * @returns {Promise<this>}
    * @example
    * await contact.sync()
+   * @private
    */
   public async sync (): Promise<void> {
     await this.ready(true)

src/user/message.ts

@@ -328,6 +328,7 @@ export class Message extends Accessory implements Sayable {
   public async say (contact: Contact)                               : Promise<void>
   public async say (file:    FileBox)                               : Promise<void>
 
+  public async say (...args: never[]): Promise<never>
   /**
    * Reply a Text or Media File message to the sender.
    * > Tips:
@@ -578,6 +579,7 @@ export class Message extends Accessory implements Sayable {
    * @description
    * should use {@link Message#mention} instead
    * @deprecated
+   * @private
    */
   public async mentioned (): Promise<Contact[]> {
     log.warn('Message', 'mentioned() DEPRECATED. use mention() instead.')

src/user/room-invitation.ts

@@ -35,6 +35,10 @@ import {
   Contact,
 }               from './contact'
 
+/**
+ *
+ * accept room invitation
+ */
 export class RoomInvitation extends Accessory implements Acceptable {
 
   public static load<T extends typeof RoomInvitation> (
@@ -46,7 +50,7 @@ export class RoomInvitation extends Accessory implements Acceptable {
   }
 
   /**
-   *
+   * @ignore
    * Instance Properties
    *
    */
@@ -76,7 +80,7 @@ export class RoomInvitation extends Accessory implements Acceptable {
   }
 
   /**
-   * @hidden
+   * @ignore
    */
   public async toStringAsync (): Promise<string> {
     const payload = await this.puppet.roomInvitationPayload(this.id)
@@ -179,6 +183,7 @@ export class RoomInvitation extends Accessory implements Acceptable {
 
   /**
    * List of Room Members that you known(is friend)
+   * @ignore
    */
   public async roomMemberList (): Promise<Contact[]> {
     log.verbose('RoomInvitation', 'roomMemberList()')
@@ -198,6 +203,11 @@ export class RoomInvitation extends Accessory implements Acceptable {
     return contactList
   }
 
+  /**
+   * Get the invitation time
+   *
+   * @returns {Promise<Date>}
+   */
   public async date (): Promise<Date> {
     log.verbose('RoomInvitation', 'date()')
 

src/user/room.ts

@@ -314,7 +314,7 @@ export class Room extends Accessory implements Sayable {
   }
 
   /**
-   * @hidden
+   * @private
    */
   public async ready (
     dirty = false,
@@ -349,7 +349,7 @@ export class Room extends Accessory implements Sayable {
   }
 
   /**
-   * @hidden
+   * @private
    */
   public isReady (): boolean {
     return !!(this.payload)
@@ -359,7 +359,8 @@ export class Room extends Accessory implements Sayable {
   public say (text: string, mention: Contact)   : Promise<void>
   public say (text: string, mention: Contact[]) : Promise<void>
   public say (file: FileBox)                    : Promise<void>
-  public say (text: never, ...args: never[])    : never
+
+  public say (...args: never[]): never
 
   /**
    * Send message inside Room, if set [replyTo], wechaty will mention the contact as well.
@@ -486,7 +487,7 @@ export class Room extends Accessory implements Sayable {
    * // 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('join', (room: Room, inviteeList: Contact[], inviter: Contact) => {
+   *   room.on('join', (room, inviteeList, inviter) => {
    *     const nameList = inviteeList.map(c => c.name()).join(',')
    *     console.log(`Room got new member ${nameList}, invited by ${inviter}`)
    *   })
@@ -498,7 +499,7 @@ export class Room extends Accessory implements Sayable {
    * // 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('leave', (room: Room, leaverList: Contact[]) => {
+   *   room.on('leave', (room, leaverList) => {
    *     const nameList = leaverList.map(c => c.name()).join(',')
    *     console.log(`Room lost member ${nameList}`)
    *   })
@@ -510,7 +511,7 @@ export class Room extends Accessory implements Sayable {
    * // 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('topic', (room: Room, topic: string, oldTopic: string, changer: Contact) => {
+   *   room.on('topic', (room, topic, oldTopic, changer) => {
    *     console.log(`Room topic changed from ${oldTopic} to ${topic} by ${changer.name()}`)
    *   })
    * }
@@ -935,6 +936,7 @@ export class Room extends Accessory implements Sayable {
    * @returns {Promise<void>}
    * @example
    * await room.sync()
+   * @private
    */
   public async sync (): Promise<void> {
     await this.ready(true)

src/wechaty.ts

@@ -102,6 +102,8 @@ export interface WechatyOptions {
   ioToken?       : string,                  // Io TOKEN
 }
 
+const PUPPET_MEMORY_NAME = 'puppet'
+
 /**
  * Main bot class.
  *
@@ -324,6 +326,7 @@ export class Wechaty extends Accessory implements Sayable {
    * @property   {string}  room-join  - Emit when anyone join any room.
    * @property   {string}  room-topic - Get topic event, emitted when someone change room topic.
    * @property   {string}  room-leave - Emit when anyone leave the room.<br>
+   * @property   {string}  room-invite - Emit when there is a room invitation, see more in  {@link RoomInvitation}
    *                                    If someone leaves the room by themselves, wechat will not notice other people in the room, so the bot will never get the "leave" event.
    * @property   {string}  scan       - A scan event will be emitted when the bot needs to show you a QR Code for scanning. </br>
    *                                    It is recommend to install qrcode-terminal(run `npm install qrcode-terminal`) in order to show qrcode in the terminal.
@@ -352,6 +355,8 @@ export class Wechaty extends Accessory implements Sayable {
    * @property   {Function} room-join       -(this: Wechaty, room: Room, inviteeList: Contact[],  inviter: Contact) => void
    * @property   {Function} room-topic      -(this: Wechaty, room: Room, newTopic: string, oldTopic: string, changer: Contact) => void
    * @property   {Function} room-leave      -(this: Wechaty, room: Room, leaverList: Contact[]) => void
+   * @property   {Function} room-invite     -(this: Wechaty, room: Room, leaverList: Contact[]) => void <br>
+   *                                        see more in  {@link RoomInvitation}
    */
 
   /**
@@ -377,35 +382,35 @@ export class Wechaty extends Accessory implements Sayable {
    * @example <caption>Event:scan</caption>
    * // Scan Event will emit when the bot needs to show you a QR Code for scanning
    *
-   * bot.on('scan', (url: string, code: number) => {
+   * bot.on('scan', (url, code) => {
    *   console.log(`[${code}] Scan ${url} to login.` )
    * })
    *
    * @example <caption>Event:login </caption>
    * // Login Event will emit when bot login full successful.
    *
-   * bot.on('login', (user: ContactSelf) => {
+   * bot.on('login', (user) => {
    *   console.log(`user ${user} login`)
    * })
    *
    * @example <caption>Event:logout </caption>
    * // Logout Event will emit when bot detected log out.
    *
-   * bot.on('logout', (user: ContactSelf) => {
+   * bot.on('logout', (user) => {
    *   console.log(`user ${user} logout`)
    * })
    *
    * @example <caption>Event:message </caption>
    * // Message Event will emit when there's a new message.
    *
-   * wechaty.on('message', (message: Message) => {
+   * wechaty.on('message', (message) => {
    *   console.log(`message ${message} received`)
    * })
    *
    * @example <caption>Event:friendship </caption>
    * // Friendship Event will emit when got a new friend request, or friendship is confirmed.
    *
-   * bot.on('friendship', (friendship: Friendship) => {
+   * bot.on('friendship', (friendship) => {
    *   if(friendship.type() === Friendship.Type.RECEIVE){ // 1. receive new friendship request from new contact
    *     const contact = friendship.contact()
    *     let result = await friendship.accept()
@@ -422,7 +427,7 @@ export class Wechaty extends Accessory implements Sayable {
    * @example <caption>Event:room-join </caption>
    * // room-join Event will emit when someone join the room.
    *
-   * bot.on('room-join', (room: Room, inviteeList: Contact[], inviter: Contact) => {
+   * bot.on('room-join', (room, inviteeList, inviter) => {
    *   const nameList = inviteeList.map(c => c.name()).join(',')
    *   console.log(`Room ${room.topic()} got new member ${nameList}, invited by ${inviter}`)
    * })
@@ -430,7 +435,7 @@ export class Wechaty extends Accessory implements Sayable {
    * @example <caption>Event:room-leave </caption>
    * // room-leave Event will emit when someone leave the room.
    *
-   * bot.on('room-leave', (room: Room, leaverList: Contact[]) => {
+   * bot.on('room-leave', (room, leaverList) => {
    *   const nameList = leaverList.map(c => c.name()).join(',')
    *   console.log(`Room ${room.topic()} lost member ${nameList}`)
    * })
@@ -438,10 +443,22 @@ export class Wechaty extends Accessory implements Sayable {
    * @example <caption>Event:room-topic </caption>
    * // room-topic Event will emit when someone change the room's topic.
    *
-   * bot.on('room-topic', (room: Room, topic: string, oldTopic: string, changer: Contact) => {
+   * bot.on('room-topic', (room, topic, oldTopic, changer) => {
    *   console.log(`Room ${room.topic()} topic changed from ${oldTopic} to ${topic} by ${changer.name()}`)
    * })
    *
+   * @example <caption>Event:room-invite, RoomInvitation has been encapsulated as a RoomInvitation Class. </caption>
+   * // room-invite Event will emit when there's an room invitation.
+   *
+   * bot.on('room-invite', async roomInvitation => {
+   *   try {
+   *     console.log(`received room-invite event.`)
+   *     await roomInvitation.accept()
+   *   } catch (e) {
+   *     console.error(e)
+   *   }
+   * }
+   *
    * @example <caption>Event:error </caption>
    * // error Event will emit when there's an error occurred.
    *
@@ -533,7 +550,7 @@ export class Wechaty extends Accessory implements Sayable {
     }
 
     const puppet       = this.options.puppet || config.systemPuppetName()
-    const puppetMemory = this.memory.sub(puppet.toString())
+    const puppetMemory = this.memory.sub(PUPPET_MEMORY_NAME)
 
     const puppetInstance = await PuppetManager.resolve({
       puppet,
@@ -728,6 +745,7 @@ export class Wechaty extends Accessory implements Sayable {
    * @desc
    * use {@link Wechaty#start} instead
    * @deprecated
+   * @private
    */
   public async init (): Promise<void> {
     log.warn('Wechaty', 'init() DEPRECATED. use start() instead.')
@@ -910,6 +928,7 @@ export class Wechaty extends Accessory implements Sayable {
    * @description
    * Should use {@link Wechaty#userSelf} instead
    * @deprecated Use `userSelf()` instead
+   * @private
    */
   public self (): Contact {
     log.warn('Wechaty', 'self() DEPRECATED. use userSelf() instead.')
@@ -930,6 +949,12 @@ export class Wechaty extends Accessory implements Sayable {
     return user
   }
 
+  public async say (text: string)     : Promise<void>
+  public async say (contact: Contact) : Promise<void>
+  public async say (file: FileBox)    : Promise<void>
+
+  public async say (...args: never[]): Promise<never>
+
   /**
    * Send message to userSelf, in other words, bot send message to itself.
    * > Tips:
@@ -960,9 +985,10 @@ export class Wechaty extends Accessory implements Sayable {
    *
    * // 4. send Image to bot itself from local file
    * import { FileBox }  from 'file-box'
-   * const fileBox = FileBox.fromLocal('/tmp/text.jpg')
+   * const fileBox = FileBox.fromFile('/tmp/text.jpg')
    * await bot.say(fileBox)
    */
+
   public async say (textOrContactOrFile: string | Contact | FileBox): Promise<void> {
     log.verbose('Wechaty', 'say(%s)', textOrContactOrFile)
 

tests/fixtures/smoke-testing.ts

@@ -2,7 +2,7 @@
 
 import { Wechaty }    from 'wechaty'
 
-function getBotList() {
+function getBotList () {
   return [
     new Wechaty({ puppet: 'wechaty-puppet-mock' }),
     new Wechaty({ puppet: 'wechaty-puppet-wechat4u' }),
@@ -16,7 +16,7 @@ function getBotList() {
   ]
 }
 
-async function main() {
+async function main () {
   const botList = getBotList()
   try {
     await Promise.all(