Merge pull request #7 from ShellMonkeys/enhance-v1.4

enhancement

.gitignore

@@ -14,3 +14,6 @@ dist
 .nyc_output
 coverage
 .coveralls.yml
+
+# Logging
+*.log

.npmignore

@@ -10,6 +10,7 @@ node_modules
 # Source directory
 src
 dist
+test
 
 # Code coverage
 .nyc_output

.travis.yml

@@ -1,6 +1,10 @@
 sudo: false
 language: node_js
+notifications:
+    email: false
 node_js:
-    - '6'
-    - '7'
-after_sucess: npm run coverage
+    - 6
+    - 7
+script:
+    - npm t
+    - npm run coverage

README.md

@@ -1,91 +1,266 @@
-<H2>fb-messenger-es6</H2>
+# fb-messenger-es6
+___
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![Build Status](https://img.shields.io/travis/ShellMonkeys/fb-messenger-es6.svg)](https://travis-ci.org/ShellMonkeys/fb-messenger-es6)
 [![Coverage Status](https://img.shields.io/coveralls/ShellMonkeys/fb-messenger-es6.svg)](https://coveralls.io/github/ShellMonkeys/fb-messenger-es6)
 
 Library to work with [Facebook Messenger APIs](https://developers.facebook.com/docs/…).
 
+Table of Contents
+=================
+* [Setup](#setup)
+* [Creating facebook app](#creating-facebook-app)
+* [Conversation](#conversation)
+  * [Sending Messages](#sending-messages)
+  * [Receiving Messages](#receiving-messages)
+* [User Profile](#user-profile)
+* [Messenger Profile](#messenger-profile)
+* [Contributing](#contributing)
 
-<H3>Installation</H3>
+## Setup
 
-Install:
+Install
 ```
 npm install fb-messenger-es6
 ```
-Import:
+Import
 ```javascript
 import  { Client } from 'fb-messenger-es6';
 ```
-Initialize:
+Initialize
 ```javascript
 const facebook = new Client(<PAGE_ACCESS_TOKEN>);
 ```
-If you need to use proxy:
+Using proxy
 ```javascript
 const facebook = new Client(<PAGE_ACCESS_TOKEN>, { hostname:<PROXY_HOSTNAME>, port: <PROXY_PORT> });
 ```
+Specify the Graph API version
 
+Accepted versions: `v2.6`, `v2.7`, `v2.8`
+```javascript
+const facebook = new Client(<PAGE_ACCESS_TOKEN>, null, API_VERSION);
+```
 
-<H3>Creating facebook app</H3>
+## Creating facebook app
 [See facebook tutorial](https://developers.facebook.com/docs/messenger-platform/guides/quick-start)
 
 
-<H3>Sending messages</H3>
-<H4>Text Message</H4>
+## Conversation
+### Sending Messages
+#### Text Message
 ```javascript
 // basic message
-facebook.send(new TextMessage('hello, world!'), <recipient_id>);
+facebook.sendMessage(new TextMessage('hello, world!'), USER_ID);
 
 // message with quick reply
-facebook.send(new TextMessage('truth or dare?')
+facebook.sendMessage(new TextMessage('truth or dare?')
     .addQuickReply(new TextQuickReply('truth'))
-    .addQuickReply(new TextQuickReply('dare')), <recipient_id>);
+    .addQuickReply(new TextQuickReply('dare')), USER_ID);
+```
+
+#### Sender Actions
+```javascript
+// Mark last message as read
+facebook.markSeen(USER_ID);
+
+// Toggle typing indicators on or off
+facebook.typingToggle(true, USER_ID); // true - on; false - off
+
+// Alternatively
+// Note: facebook.senderActions has been deprecated
+facebook.sendAction(SENDER_ACTION, USER_ID);
 ```
 
-<H4>Sender Actions </H4>
+#### Attachment Reuse
 ```javascript
-facebook.senderActions('mark_seen', <recipient_id>);
+const attachmentId = facebook.upload(new ImageAttachment('https://myapp.com/img/image.png'));
+
+// subsequent calls using attachment_id
+facebook.sendMessage(new ImageAttachment(null, attachmentId));
 ```
 
-<H4>Others supported</H4>
-- Content Types
-    - Text
+#### Supported Messages
+- Text Messages
+- Rich Media Messages (with attachment reuse)
     - Image
-- Templates
+    - Video
+    - Audio
+    - File
+- Structured Messages
     - Button Template
     - Generic Template
     - List Template
 - Buttons
-    - URL Button
-    - Postback Button
-    - Call Button
-    - Share Button
+    - URL button
+    - Postback button
+    - Call button
+    - Share button
     - Log In and Log Out buttons
-- Quick Replies
+- Quick Replies (works in text, rich media & structured messages)
+
+More to be added later
+
+### Receiving Messages
+This section has code snippets for an express.js app
+
+You should validate the signature before proceeding
+```javascript
+import bodyParser from 'body-parser';
+import { ValidateSignature } from 'fb-messenger-es6';
+...
+const validator = new ValidateSignature(APP_SECRET);
+app.post('/webhook', bodyParser.json({ verify: (req, res, bf) => validator.validate(req, res, bf) }));
+```
+
+You can process the callbacks using `ProcessIncoming` which returns a minimal version of the callback to make it easier to handle
+```javascript
+import { ProcessIncoming } from 'fb-messenger-es6';
+...
+app.use('/webhook', (req, res) => {
+    if (req.method === 'GET') {
+        if (req.query['hub.mode'] === 'subscribe' &&
+            req.query['hub.verify_token'] === VERIFY_TOKEN) {
+            return res.status(200).send(req.query['hub.challenge']);
+        }
+        return res.sendStatus(403);
+    }
+    else if (req.method === 'POST') {
+        // Facebook requires a 200 OK HTTP res as fast as possible
+        res.sendStatus(200);
+
+        // NOTE: ProcessIncoming returns messages grouped by PAGE_ID
+        const messages = ProcessIncoming(req.body);
+
+        for (const message of messages[PAGE_ID]){
+            handleMessage(message);
+        }
+    }
+});
+```
+#### `ProcessIncoming`
+Messages are grouped by PAGE_ID and contain callback default fields (`sender`, `recipient`, `timestamp`, `type`) and additional callback specific fields
+```javascript
+{
+    PAGE_ID: [
+        {
+            sender: 'USER_ID',
+            recipient: 'PAGE_ID',
+            timestamp: 1458692752478,
+            type: '???', // message or message_read or message_echo or message_delivery or postback or account_linking
+            ...CALLBACK_SPECIFIC_FIELDS,
+        },
+    ],
+}
+```
 
-More to be added
+Below are the various `CALLBACK_SPECIFIC_FIELDS` returned after processing a callback:
+##### Message
+The callback default field `type` is `message`
 
-<H3>User Profile</H3>
+**Text Message**
+```javascript
+{
+    ...CALLBACK_DEFAULT_FIELDS,
+    text: 'hello, world!',
+    quick_reply: 'DEVELOPER_DEFINED_PAYLOAD', // optional
+}
+```
+**Rich Media  Messages**
+
+NOTE: `attachment.type` can be `image`, `audio`, `video` or `file`
+```javascript
+{
+    ...CALLBACK_DEFAULT_FIELDS,
+    attachments: [
+        {
+            type: '???', // image or audio or video or file
+            url: 'ATTACHMENT_URL',
+        },
+    ],
+}
+```
+**Stickers**
+
+When processing sticker messages, pass in your stickers map to text so you get `sticker_type`
+```javascript
+{
+    ...CALLBACK_DEFAULT_FIELDS,
+    attachments: [
+        {
+            type: 'sticker',
+            sticker_id: 369239343222814,
+            sticker_type: 'LIKE',
+        },
+    ],
+}
+```
+**Location**
+```javascript
+{
+    ...CALLBACK_DEFAULT_FIELDS,
+    attachments: [
+        {
+            type: 'location',
+            long: '-79.411079',
+            lat: '43.761539',
+        },
+    ],
+}
+```
+##### Message Delivered, Message Read & Message Echo
+The callback default field `type` changes to `message_delivery`, `message_read` & `message_echo` respectively.
+There are no callback specific fields
+
+##### Postback
+The callback default field `type` is `postback`
+```javascript
+{
+    ...CALLBACK_DEFAULT_FIELDS,
+    payload: 'USER_DEFINED_PAYLOAD',
+}
+```
+##### Account Linking Event
+The callback default field `type` is `account_linking`
+```javascript
+{
+    ...CALLBACK_DEFAULT_FIELDS,
+    status: 'linked',
+    authorization_code: 'PASS_THROUGH_AUTHORIZATION_CODE',
+}
+```
+
+## User Profile
+```javascript
+// if no second arg, it defaults to all
+// possible fields ['first_name', 'last_name', 'profile_pic', 'locale', 'timezone', 'gender', 'is_payment_enabled']
+facebook.getUserProfile(<USER_ID>);
+
+// To specify fields, pass in a second arg
+facebook.getUserProfile(<USER_ID>, ['is_payment_enabled']);
+```
+## Messenger Profile
 ```javascript
-facebook.getProfile(<USER_ID>);// if no second arg, it defaults to all - ['first_name', 'last_name', 'profile_pic', 'locale', 'timezone', 'gender']
+import { MessengerProfile } from 'fb-messenger-es6';
 ```
-<H3>Messenger Profile</H3>
-All except payments settings are supported
-<H4>Setting properties</H4>
+### Setting properties
 ```javascript
-facebook.updateBotSettings(new MessengerProfile().setGetStartedButton('Get Started')
+// NOTE: facebook.updateBotSettings has been deprecated
+facebook.setMessengerProfile(new MessengerProfile().setGetStartedButton('Get Started')
     .addGreetingText(new GreetingText('hello, world')));
 ```
-<H4>Reading properties</H4>
+### Reading properties
 ```javascript
-facebook.viewBotSettings(new MessengerProfile().setFields['greeting', 'get_started']);
+// NOTE: facebook.viewBotSettings has been deprecated
+facebook.getMessengerProfile(new MessengerProfile().setFields(['greeting', 'get_started']));
 ```
-<H4>Deleting properties</H4>
+### Deleting properties
 ```javascript
-facebook.deleteBotSettings(new MessengerProfile().setFields['greeting', 'get_started']);
+// NOTE: facebook.deleteBotSettings has been deprecated
+facebook.deleteMessengerProfile(new MessengerProfile().setFields(['greeting', 'get_started']));
 ```
 
-<H3>Contributing</H3>
-If you would like to contribute, you can fork the repository and send us pull requests.
+## Contributing
+If you would like to contribute, you can fork the repository and send us pull reqs.
 
 When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "fb-messenger-es6",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "Facebook Messenger plaform library",
   "main": "dist",
   "scripts": {