Merge pull request #138 from watson-developer-cloud/assistant

feat: Add semantic releases and IAM support

Author: mamoonraja

.eslintrc.yml

@@ -0,0 +1,19 @@
+env:
+  node: true
+  mocha: true
+extends: 'eslint:recommended'
+rules:
+  indent:
+    - error
+    - 2
+  linebreak-style:
+    - error
+    - unix
+  quotes:
+    - error
+    - single
+  semi:
+    - error
+    - always
+  no-console:
+    - off

.travis.yml

@@ -1,10 +1,22 @@
 language: node_js
-sudo: false
-node_js: 6
+sudo: true
+node_js: 8
 cache:
   directories:
     - node_modules
 script:
+  - npm run lint
   - npm test
-notifications:
-  email: false
+deploy:
+- provider: script
+  skip_cleanup: true
+  script:
+  - bx-blue-green-travis
+  on:
+    branch: master
+    repo: watson-developer-cloud/botkit-middleware
+- provider: script
+  skip_cleanup: true
+  script: npx semantic-release
+  on:
+    node: 8

CHANGELOG.md

@@ -1,3 +1,9 @@
+## v1.8.0
+
+* Added semantic-releases
+* Update node-sdk to 3.7.0
+* Update to use the Watson Assistant class
+
 ## v1.6.1
 
 * Fixed function signatures in Typescript definition file

README.md

@@ -1,6 +1,6 @@
-# Use IBM Watson's Conversation service to chat with your Botkit-powered Bot! [![Build Status](https://travis-ci.org/watson-developer-cloud/botkit-middleware.svg?branch=master)](https://travis-ci.org/watson-developer-cloud/botkit-middleware)
+# Use IBM Watson's Assistant service to chat with your Botkit-powered Bot! [![Build Status](https://travis-ci.org/watson-developer-cloud/botkit-middleware.svg?branch=master)](https://travis-ci.org/watson-developer-cloud/botkit-middleware)
 
-This middleware plugin for [Botkit](http://howdy.ai/botkit) allows developers to easily integrate a [Watson Conversation](https://www.ibm.com/watson/developercloud/conversation.html) workspace with multiple social channels like Slack, Facebook, and Twilio. Customers can have simultaneous, independent conversations with a single workspace through different channels.
+This middleware plugin for [Botkit](http://howdy.ai/botkit) allows developers to easily integrate a [Watson Assistant](https://www.ibm.com/watson/services/conversation/) workspace with multiple social channels like Slack, Facebook, and Twilio. Customers can have simultaneous, independent conversations with a single workspace through different channels.
 
 ## Middleware Overview
 
@@ -18,7 +18,7 @@ This middleware plugin for [Botkit](http://howdy.ai/botkit) allows developers to
 * `hear`: used for [intent matching](#intent-matching).
 * `updateContext`: used in [implementing app actions](#implementing-app-actions) (sendToWatson does it better now).
 * `readContext`: used in [implementing event handlers](#implementing-event-handlers).
-* `before`: [pre-process](#before-and-after) requests before sending to Watson Conversation (Conversation).
+* `before`: [pre-process](#before-and-after) requests before sending to Watson Assistant (Conversation).
 * `after`: [post-process](#before-and-after) responses before forwarding them to Botkit.
 
 
@@ -28,18 +28,26 @@ This middleware plugin for [Botkit](http://howdy.ai/botkit) allows developers to
 $ npm install botkit-middleware-watson --save
 ```
 
-## Usage
+## Prerequisites
 
-### Acquire Watson Conversation credentials
+1. Sign up for an [IBM Cloud account](https://console.bluemix.net/registration/).
+1. Download the [IBM Cloud CLI](https://console.bluemix.net/docs/cli/index.html#overview).
+1. Create an instance of the Watson Assistant service and get your credentials:
+    - Go to the [Watson Assistant](https://console.bluemix.net/catalog/services/conversation) page in the IBM Cloud Catalog.
+    - Log in to your IBM Cloud account.
+    - Click **Create**.
+    - Click **Show** to view the service credentials.
+    - Copy the `apikey` value, or copy the `username` and `password` values if your service instance doesn't provide an `apikey`.
+    - Copy the `url` value.
 
-The middleware needs you to provide the `username`, `password`, and `workspace_id` of your Watson Conversation chat bot. If you have an existing Conversation service instance, follow [these steps](https://github.com/watson-developer-cloud/conversation-simple/blob/master/README.md#configuring-the-application-environmnet) to get your credentials.
+1. Create a workspace using the Watson Assistant service and copy the `workspace_id`.
 
-If you do not have a Conversation service instance,  follow [these steps](https://github.com/watson-developer-cloud/conversation-simple/blob/master/README.md#before-you-begin) to get started.
 
 ### Acquire channel credentials
-This document shows code snippets for using a Slack bot with the middleware. (If you want examples for the other channels, see the [examples/multi-bot](/examples/multi-bot) folder. The multi-bot example app shows how to connect to Slack, Facebook, and Twilio IPM bots running on a single Express server.)
+This document shows code snippets for using a Slack bot with the middleware. (If you want examples for the other channels, see the [examples/multi-bot](/examples/multi-bot) folder.
+The multi-bot example app shows how to connect to Slack, Facebook, and Twilio IPM bots running on a single Express server.)
 
-You need a _Slack token_ for your Slack bot to talk to Conversation.
+You need a _Slack token_ for your Slack bot to talk to Watson Assistant.
 
 If you have an existing Slack bot, then copy the Slack token from your Slack settings page.
 
@@ -61,13 +69,29 @@ var slackBot = slackController.spawn({
 });
 ```
 
-Create the middleware object which you'll use to connect to the Conversation service:
+Create the middleware object which you'll use to connect to the Watson Assistant service.
+
+If your credentials are `username` and `password` use:
+
+```js
+var watsonMiddleware = require('botkit-middleware-watson')({
+  username: YOUR_ASSISTANT_USERNAME,
+  password: YOUR_ASSISTANT_PASSWORD,
+  url: YOUR_ASSISTANT_URL,
+  workspace_id: YOUR_WORKSPACE_ID,
+  version: '2018-07-10',
+  minimum_confidence: 0.50, // (Optional) Default is 0.75
+});
+```
+
+If your credentials is `apikey` use:
+
 ```js
 var watsonMiddleware = require('botkit-middleware-watson')({
-  username: YOUR_CONVERSATION_USERNAME,
-  password: YOUR_CONVERSATION_PASSWORD,
+  iam_apikey: YOUR_API_KEY,
+  url: YOUR_ASSISTANT_URL,
   workspace_id: YOUR_WORKSPACE_ID,
-  version_date: '2017-05-26',
+  version: '2018-07-10',
   minimum_confidence: 0.50, // (Optional) Default is 0.75
 });
 ```
@@ -98,7 +122,7 @@ Then you're all set!
 ### Message filtering
 
 When middleware is registered, the receive function is triggered on _every_ message.
-If you would like to make your bot to only respond to _direct messages_ using Conversation, you can achieve this in 2 ways:
+If you would like to make your bot to only respond to _direct messages_ using Assistant, you can achieve this in 2 ways:
 
 #### Using interpret function instead of registering middleware
 
@@ -161,7 +185,7 @@ Note: if you want your own `hear()` function to implement pattern matching like
 
 ### Implementing app actions
 
-Conversation side of app action is documented in [Developer Cloud](https://www.ibm.com/watson/developercloud/doc/conversation/develop-app.html#implementing-app-actions)
+Watson Assistant side of app action is documented in [Developer Cloud](https://console.bluemix.net/docs/services/conversation/develop-app.html#building-a-client-application)
 A common scenario of processing actions is
 * Send message to user "Please wait while I ..."
 * Perform action
@@ -374,21 +398,21 @@ slackController.hears(['hello'], ['direct_message', 'direct_mention', 'mention']
 
 #### `before` and `after`
 
-The _before_ and _after_ callbacks can be used to perform some tasks _before_ and _after_ Conversation is called. One may use it to modify the request/response payloads, execute business logic like accessing a database or making calls to external services.
+The _before_ and _after_ callbacks can be used to perform some tasks _before_ and _after_ Assistant is called. One may use it to modify the request/response payloads, execute business logic like accessing a database or making calls to external services.
 
 They can be customized as follows:
 
 ```js
-middleware.before = function(message, conversationPayload, callback) {
-  // Code here gets executed before making the call to Conversation.
+middleware.before = function(message, assistantPayload, callback) {
+  // Code here gets executed before making the call to Assistant.
   callback(null, customizedPayload);
 }
 ```
 
 ```js
-  middleware.after = function(message, conversationResponse, callback) {
-    // Code here gets executed after the call to Conversation.
-    callback(null, conversationResponse);
+  middleware.after = function(message, assistantResponse, callback) {
+    // Code here gets executed after the call to Assistant.
+    callback(null, assistantResponse);
   }
 ```
 

examples/multi-bot/.env

@@ -1,13 +1,16 @@
 #WATSON
-# Set CONVERSATION_URL to correct gateway
+# Set ASSISTANT_URL to correct gateway
 # US-South
-CONVERSATION_URL=https://gateway.watsonplatform.net/conversation/api
+ASSISTANT_URL=https://gateway.watsonplatform.net/assistant/api
 # Germany
-#CONVERSATION_URL=https://gateway-fra.watsonplatform.net/conversation/api
-CONVERSATION_USERNAME=username
-CONVERSATION_PASSWORD=password
+#ASSISTANT_URL=https://gateway-fra.watsonplatform.net/assistant/api
+ASSISTANT_USERNAME=username
+ASSISTANT_PASSWORD=password
 WORKSPACE_ID=your_workspace_id
 
+# if is apikey
+#ASSISTANT_IAM_APIKEY=apikey
+
 #SLACK
 SLACK_TOKEN=your_slack_bot_token
 

examples/multi-bot/README.md

@@ -10,10 +10,45 @@ This document describes how to set up a sample Express app which talks to Slack,
 
 ## Getting credentials
 
-### Watson Conversation
-Follow the steps outlined in [this document](https://github.com/watson-developer-cloud/conversation-simple/blob/master/README.md#configuring-the-app-environment) and paste your Conversation bot's credentials in the sample `.env` file in the project directory.
+### Watson Assistant
+
+1. Sign up for an [IBM Cloud account](https://console.bluemix.net/registration/).
+1. Download the [IBM Cloud CLI](https://console.bluemix.net/docs/cli/index.html#overview).
+1. Create an instance of the Watson Assistant service and get your credentials:
+    - Go to the [Watson Assistant](https://console.bluemix.net/catalog/services/conversation) page in the IBM Cloud Catalog.
+    - Log in to your IBM Cloud account.
+    - Click **Create**.
+    - Click **Show** to view the service credentials.
+    - Copy the `apikey` value, or copy the `username` and `password` values if your service instance doesn't provide an `apikey`.
+    - Copy the `url` value.
+
+1. Create a workspace using the Watson Assistant service and copy the `workspace_id`.
+
+1. Open the *.env* file and add the service credentials that you obtained in the previous step.
+
+    Example *.env* file that configures the `apikey` and `url` for a Watson Assistant service instance hosted in the US East region:
+
+    ```
+    ASSISTANT_IAM_APIKEY=X4rbi8vwZmKpXfowaS3GAsA7vdy17Qh7km5D6EzKLHL2
+    ASSISTANT_URL=https://gateway-wdc.watsonplatform.net/assistant/api
+    ```
+
+    - If your service instance uses `username` and `password` credentials, add the `ASSISTANT_USERNAME` and `ASSISTANT_PASSWORD` variables to the *.env* file.
+
+    Example *.env* file that configures the `username`, `password`, and `url` for a Watson Assistant service instance hosted in the US South region:
+
+    ```
+    ASSISTANT_USERNAME=522be-7b41-ab44-dec3-g1eab2ha73c6
+    ASSISTANT_PASSWORD=A4Z5BdGENrwu8
+    ASSISTANT_URL=https://gateway.watsonplatform.net/assistant/api
+    ```
+
+1. Add the `WORKSPACE_ID` to the previous properties
+
+    ```
+    WORKSPACE_ID=522be-7b41-ab44-dec3-g1eab2ha73c6
+    ```
 
-If you don't have a Conversation service instance,  follow [these steps](https://github.com/watson-developer-cloud/conversation-simple/blob/master/README.md#before-you-begin) to get started.
 
 ### Slack
 Follow the Getting Started section of this [document](https://github.com/howdyai/botkit/blob/master/docs/readme-slack.md) from Botkit.
@@ -43,7 +78,7 @@ FB_VERIFY_TOKEN=<your verify token>
 FB_APP_SECRET=<your apps secret key>
 ```
 
-When you're ready to test your bot, go to your Facebook homepage and find the page you created. Click on _Message_ to start chatting with your Watson Conversation bot!
+When you're ready to test your bot, go to your Facebook homepage and find the page you created. Click on _Message_ to start chatting with your Watson Assistant bot!
 
 ### Twilio IPM
 Follow the Getting Started section of this [document](https://github.com/howdyai/botkit/blob/master/docs/readme-twilioipm.md) from Botkit.

examples/multi-bot/app.js

@@ -17,11 +17,11 @@
 require('dotenv').load();
 
 var middleware = require('botkit-middleware-watson')({
-  username: process.env.CONVERSATION_USERNAME,
-  password: process.env.CONVERSATION_PASSWORD,
+  username: process.env.ASSISTANT_USERNAME,
+  password: process.env.ASSISTANT_PASSWORD,
   workspace_id: process.env.WORKSPACE_ID,
-  url: process.env.CONVERSATION_URL || 'https://gateway.watsonplatform.net/conversation/api',
-  version_date: '2017-05-26'
+  url: process.env.ASSISTANT_URL || 'https://gateway.watsonplatform.net/assistant/api',
+  version: '2018-07-10'
 });
 
 module.exports = function(app) {
@@ -44,11 +44,11 @@ module.exports = function(app) {
     console.log('Twilio bot is live');
   }
   // Customize your Watson Middleware object's before and after callbacks.
-  middleware.before = function(message, conversationPayload, callback) {
-    callback(null, conversationPayload);
-  }
+  middleware.before = function(message, assistantPayload, callback) {
+    callback(null, assistantPayload);
+  };
 
-  middleware.after = function(message, conversationResponse, callback) {
-    callback(null, conversationResponse);
-  }
+  middleware.after = function(message, assistantResponse, callback) {
+    callback(null, assistantResponse);
+  };
 };

examples/multi-bot/bot-facebook.js

@@ -30,7 +30,7 @@ controller.hears('(.*)', 'message_received', function(bot, message) {
     bot.reply(message, message.watsonData.output.text.join('\n'));
   } else {
     console.log('Error: received message in unknown format. (Is your connection with Watson Conversation up and running?)');
-    bot.reply(message, "I'm sorry, but for technical reasons I can't respond to your message");
+    bot.reply(message, 'I\'m sorry, but for technical reasons I can\'t respond to your message');
   }
 });
 

examples/multi-bot/bot-slack.js

@@ -29,7 +29,7 @@ controller.hears(['.*'], ['direct_message', 'direct_mention', 'mention'], functi
     bot.reply(message, message.watsonData.output.text.join('\n'));
   } else {
     console.log('Error: received message in unknown format. (Is your connection with Watson Conversation up and running?)');
-    bot.reply(message, "I'm sorry, but for technical reasons I can't respond to your message");
+    bot.reply(message, 'I\'m sorry, but for technical reasons I can\'t respond to your message');
   }
 });
 

examples/multi-bot/bot-twilio.js

@@ -34,7 +34,7 @@ controller.hears(['.*'], 'message_received', function(bot, message) {
     bot.reply(message, message.watsonData.output.text.join('\n'));
   } else {
     console.log('Error: received message in unknown format. (Is your connection with Watson Conversation up and running?)');
-    bot.reply(message, "I'm sorry, but for technical reasons I can't respond to your message");
+    bot.reply(message, 'I\'m sorry, but for technical reasons I can\'t respond to your message');
   }
 });