add api reference to README

README.md

@@ -133,11 +133,219 @@ npm test
 
 Get to know more about the tests from [Wiki:Tests](https://github.com/chatie/wechaty/wiki/Tests)
 
-## DOCUMATAION
+## API
 
-In order to sync the doc with the lastest code, we are using [jsdoc](http://usejsdoc.org/) to describe the API, and use [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown/wiki) to generate markdown format documents to the [docs](docs/index.md) directory.
+This is a overview of most of the easy to use Wechaty APIs.
 
-See: [Official API Reference](https://chatie.github.io/wechaty/)
+You can get the full Documentation from [Wechaty Official API Reference](https://chatie.github.io/wechaty/)
+
+### 1 Class `Wechaty`
+
+Main bot class.
+
+A `Bot` is a Wechaty instance that control a specific [wechaty-puppet](https://github.com/Chatie/wechaty/wiki/Puppet).
+
+#### 1.1 `new Wechaty(options: WechatyOptions)`
+
+1. `options.name?: string` the name to identify this bot
+2. `optoins.puppet?: string` select which puppet we use. must be one of
+    1. [wechaty-puppet-puppeteer](https://github.com/chatie/wechaty-puppet-puppeteer) - Angular Hook for Web Wechat <- This is the DEFAULT
+    2. [wechaty-puppet-wechat4u](https://github.com/chatie/wechaty-puppet-wechat4u) - HTTP API for Web Wechat
+    3. [wechaty-puppet-padchat](https://github.com/lijiarui/wechaty-puppet-padchat) - iPad App Protocol
+    4. [wechaty-puppet-ioscat](https://github.com/linyimin-bupt/wechaty-puppet-ioscat) - iPhone App Hook
+3. `optoins.puppetOptions: PuppetOptions` puppet options.
+
+#### 1.2 `wechaty.start(): Promise<void>` start the bot
+
+#### 1.3 `wechaty.stop(): Promise<void>` stop the bot
+
+#### 1.4 `wechaty.logonoff(): boolean` get the bot login/logout status
+
+#### 1.5 `wechaty.logout(): Promise<void>` logout the bot
+
+#### 1.6 `wechaty.userSelf(): ContactSelf` return the login-ed bot contact
+
+#### 1.7 Event `wechaty.say(something)` let bot say something to itself
+
+#### 1.8 Event `wechaty.on('login', ...)` emit after bot login full successful
+
+#### 1.9 Event `wechaty.on('logout', ...)` emit after the bot log out
+
+#### 1.10 Event `wechaty.on('friendship`, ...)` emit when someone sends bot a friend request
+
+#### 1.11 Event `wechaty.on('message', ...)` emit when there's a new message
+
+#### 1.12 Event `wechaty.on('room-join', ...)` emit when anyone join any room
+
+#### 1.13 Event `wechaty.on('room-topic', ...)` emit when someone change room topic
+
+#### 1.14 Event `wechaty.on('room-leave', ...)` emit when anyone leave the room
+
+#### 1.15 Event `wechaty.on('room-invite', ...)` emit when there is a room invitation
+
+#### 1.16 Event `wechaty.on('scan', ...)` A scan event will be emitted when the bot needs to show you a QR Code for scanning
+
+### 2 Class `Contact`
+
+All wechat contacts(friends/non-friends) will be encapsulated as a Contact.
+
+#### 2.1 `Contact.find(query: string): Promise<Contact>`
+
+#### 2.2 `Contact.findAll(query: string): Promise<Contact[]>`
+
+#### 2.3 `contact.id: readonly string` Contact id
+
+#### 2.4 `contact.say(something): Promise<void>` say something to this contact
+
+#### 2.5 `contact.self(): boolean` whether this contact is the bot itself
+
+#### 2.6 `contact.name(): string`
+
+#### 2.7 `contact.alias(): Promise<string>` get alias
+
+#### 2.8 `contact.alias(newAlias: string): Promise<void>` set alias
+
+#### 2.9 `contact.friend(): boolean`
+
+#### 2.10 `contact.type(): ContactType`
+
+- ContactType.Unknown
+- ContactType.Personal
+- ContactType.Official
+
+#### 2.11 `contact.province(): string`
+
+#### 2.12 `contact.city(): string`
+
+#### 2.13 `contact.avatar(): Promise<FileBox>` get profile avatar from contact
+
+#### 2.14 `contact.gender(): ContactGender` get gender
+
+- ContactGender.Unknown
+- ContactGender.Male
+- ContactGender.Female
+
+### 3 Class `ContactSelf`
+
+#### 3.1 `contactSelf.avatar(file: FileBox): Promise<void>` set avatar for bot
+
+#### 3.2 `contactSelf.qrcode(): Promise<string>` get qrcode for bot
+
+#### 3.3 `contactSelf.signature(signature: string)` set signature for bot
+
+### 4 Class `Message`
+
+All wechat messages will be encapsulated as a Message.
+
+#### 4.1 `Message.find(query: string): Promise<Message>` search message in the recent cache
+
+#### 4.2 `Message.findAll(query: string): Promise<Message[]>`
+
+#### 4.3 `message.from(): Contact`
+
+#### 4.4 `message.to(): Contact`
+
+#### 4.5 `message.room(): null | Room`
+
+#### 4.6 `message.text(): string`
+
+#### 4.7 `message.say(text: string, mention?: Contact[]): Promise<void>`
+
+#### 4.8 `message.type(): MessageType`
+
+- MessageType.Text
+- MessageType.Image
+- MessageType.Audio
+- MessageType.Video
+- MessageType.Attachment
+
+#### 4.9 `message.self(): boolean`
+
+#### 4.10 `message.mention(): Contact[]`
+
+#### 4.11 `message.mentionSelf(): boolean`
+
+#### 4.12 `message.forward(to: Contact): Promise<void>`
+
+#### 4.13 `message.age(): number`
+
+#### 4.14 `message.toFileBox(): Promise<FileBox>`
+
+#### 4.15 `message.toContact(): Promise<Contact>`
+
+### 5 Class `Room`
+
+All wechat rooms(groups) will be encapsulated as a Room.
+
+#### 5.1 `room.create(contactList: Contact[], topic?: string): Promise<Room>`
+
+#### 5.2 `room.find(query: string): Promise<null | Room>`
+
+#### 5.3 `room.findAll(query?: string): Promise<room[]>`
+
+#### 5.4 `room.id: readonly string`
+
+#### 5.5 `room.say(something: string): Promise<void>`
+
+#### 5.6 `room.add(contact: Contact): Promise<void>`
+
+#### 5.7 `room.del(contact: Cotnact): Promise<void>`
+
+#### 5.8 `room.quit(): Promise<void>`
+
+#### 5.9 `room.topic(): Promise<string` get topic
+
+#### 5.10 `room.topic(newTopic: string): Promise<void>` set topic
+
+#### 5.11 `room.announce(announcement: string): Promise<void>`
+
+#### 5.12`room.qrcode(): Promise<string>` get a qrcode for joining this room
+
+#### 5.13 `room.alias(contact: Cotnact): Promise<string>` get the room alias from a room member contact
+
+#### 5.14 `room.has(contact: Contact): Promise<boolean>`
+
+#### 5.15 `room.memberAll(query?: string): Promise<Contact[]>`
+
+#### 5.16 `room.member(query: string): Promise<null | Contact>`
+
+#### 5.17 `room.owner(): null | Contact`
+
+#### 5.18 Event `room.on('join', ...)` emit when anyone join any room
+
+#### 5.19 Event `room.on('topic', ...)` emit when someone change room topic
+
+#### 5.20 Event `room.on('leave', ...)` emit when anyone leave the room
+
+### 6 Class `Friendship`
+
+Send, receive friend request, and friend confirmation events.
+
+#### 6.1 `Friendship.add(contact: Cotnact, hello?: string): Promise<void>` send a friend invitation to contact
+
+#### 6.2 `friendship.accept(): Promise<void>`
+
+#### 6.3 `friendship.hello(): string` get the hello string from a friendship invitation
+
+#### 6.4 `friendship.contact(): Contact`
+
+#### 6.5 `friendship.type(): FriendshipType`
+
+- FriendshipType.Confirm
+- FriendshipType.Receive
+- FriendshipType.Verify
+
+### 7 Class `RoomInvitation`
+
+Accept room invitation
+
+#### 7.1 `roomInvitation.accept(): Promise<void>`
+
+#### 7.2 `roomInvitation.inviter(): Contact`
+
+#### 7.3 `roomInvitation.topic(): Promise<string>`
+
+#### 7.4 `roomInvitation.date(): Date`
 
 ## RELEASE NOTES
 

src/user/contact.ts

@@ -74,8 +74,7 @@ export class Contact extends Accessory implements Sayable {
   /**
    * @private
    * About the Generic: https://stackoverflow.com/q/43003970/1123955
-   */
-  /**
+   *
    * Get Contact by id
    * > Tips:
    * This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)

src/user/friendship.ts

@@ -59,6 +59,9 @@ export class Friendship extends Accessory implements Acceptable {
   // tslint:disable-next-line:variable-name
   public static Type = FriendshipType
 
+  /**
+   * @private
+   */
   public static load<T extends typeof Friendship> (
     this : T,
     id   : string,

src/user/message.ts

@@ -152,6 +152,7 @@ export class Message extends Accessory implements Sayable {
  /**
   * Create a Mobile Terminated Message
   * @ignore
+  * @private
   * "mobile originated" or "mobile terminated"
   * https://www.tatango.com/resources/video-lessons/video-mo-mt-sms-messaging/
   */

src/user/room-invitation.ts

@@ -164,16 +164,23 @@ export class RoomInvitation extends Accessory implements Acceptable {
    * @example
    * const bot = new Wechaty()
    * bot.on('room-invite', async roomInvitation => {
-   *   const topic = await roomInvitation.roomTopic()
+   *   const topic = await roomInvitation.topic()
    *   console.log(`received room invitation event from room ${topic}`)
    * }
    * .start()
    */
-  public async roomTopic (): Promise<string> {
+  public async topic (): Promise<string> {
     const payload = await this.puppet.roomInvitationPayload(this.id)
     return payload.roomTopic
   }
 
+  /**
+   * @deprecated: use topic() instead
+   */
+  public async roomTopic (): Promise<string> {
+    return this.topic()
+  }
+
   public async roomMemberCount (): Promise<number> {
     log.verbose('RoomInvitation', 'roomMemberCount()')
 

src/user/room.ts

@@ -129,12 +129,12 @@ export class Room extends Accessory implements Sayable {
    * const roomList = await bot.Room.findAll({topic: 'wechaty'})  // find all of the rooms with name 'wechaty'
    */
   public static async findAll<T extends typeof Room> (
-    this  : T,
-    query : RoomQueryFilter = { topic: /.*/ },
+    this   : T,
+    query? : RoomQueryFilter,
   ): Promise<Array<T['prototype']>> {
     log.verbose('Room', 'findAll(%s)', JSON.stringify(query) || '')
 
-    if (!query.topic) {
+    if (query && !query.topic) {
       throw new Error('topicFilter not found')
     }
 
@@ -225,8 +225,7 @@ export class Room extends Accessory implements Sayable {
   /**
    * @private
    * About the Generic: https://stackoverflow.com/q/43003970/1123955
-   */
-  /**
+   *
    * Load room by topic. <br>
    * > Tips: For Web solution, it cannot get the unique topic id,
    * but for other solutions besides web,
@@ -771,7 +770,7 @@ export class Room extends Accessory implements Sayable {
   }
 
   /**
-   * Return contact's roomAlias in the room, the same as roomAlias
+   * Return contact's roomAlias in the room
    * @param {Contact} contact
    * @returns {Promise<string | null>} - If a contact has an alias in room, return string, otherwise return null
    * @example
@@ -788,23 +787,25 @@ export class Room extends Accessory implements Sayable {
    * .start()
    */
   public async alias (contact: Contact): Promise<null | string> {
-    return this.roomAlias(contact)
+    const memberPayload = await this.puppet.roomMemberPayload(this.id, contact.id)
+
+    if (memberPayload && memberPayload.roomAlias) {
+      return memberPayload.roomAlias
+    }
+
+    return null
   }
 
   /**
    * Same as function alias
    * @param {Contact} contact
    * @returns {Promise<string | null>}
+   * @deprecated: use room.alias() instead
+   * @private
    */
   public async roomAlias (contact: Contact): Promise<null | string> {
-
-    const memberPayload = await this.puppet.roomMemberPayload(this.id, contact.id)
-
-    if (memberPayload && memberPayload.roomAlias) {
-      return memberPayload.roomAlias
-    }
-
-    return null
+    log.warn('Room', 'roomAlias() DEPRECATED. use room.alias() instead')
+    return this.alias(contact)
   }
 
   /**
@@ -862,12 +863,16 @@ export class Room extends Accessory implements Sayable {
    * @returns {Promise<Contact[]>}
    */
   public async memberAll (
-    query: string | RoomMemberQueryFilter,
+    query?: string | RoomMemberQueryFilter,
   ): Promise<Contact[]> {
     log.silly('Room', 'memberAll(%s)',
-                      JSON.stringify(query),
+                      JSON.stringify(query) || '',
               )
 
+    if (!query) {
+      return this.memberList()
+    }
+
     const contactIdList = await this.puppet.roomMemberSearch(this.id, query)
     const contactList   = contactIdList.map(id => this.wechaty.Contact.load(id))
 
@@ -936,13 +941,15 @@ export class Room extends Accessory implements Sayable {
   }
 
   /**
+   * @private
+   *
    * Get all room member from the room
    *
    * @returns {Promise<Contact[]>}
    * @example
    * await room.memberList()
    */
-  public async memberList (): Promise<Contact[]> {
+  private async memberList (): Promise<Contact[]> {
     log.verbose('Room', 'memberList()')
 
     const memberIdList = await this.puppet.roomMemberList(this.id)
@@ -966,7 +973,7 @@ export class Room extends Accessory implements Sayable {
    * @example
    * const owner = room.owner()
    */
-  public owner (): Contact | null {
+  public owner (): null | Contact {
     log.info('Room', 'owner()')
 
     const ownerId = this.payload && this.payload.ownerId

src/wechaty.ts

@@ -329,7 +329,7 @@ export class Wechaty extends Accessory implements Sayable {
    * @property   {string}  login      - After the bot login full successful, the event login will be emitted, with a Contact of current logined user.
    * @property   {string}  logout     - Logout will be emitted when bot detected log out, with a Contact of the current login user.
    * @property   {string}  heartbeat  - Get bot's heartbeat.
-   * @property   {string}  friend     - When someone sends you a friend request, there will be a Wechaty friend event fired.
+   * @property   {string}  friendship - When someone sends you a friend request, there will be a Wechaty friendship event fired.
    * @property   {string}  message    - Emit when there's a new message.
    * @property   {string}  ready      - Emit when all data has load completed, in wechaty-puppet-padchat, it means it has sync Contact and Room completed
    * @property   {string}  room-join  - Emit when anyone join any room.