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

merge changes from master

README.md

@@ -1,4 +1,4 @@
-Watson Developer Cloud Node.js Client
+Watson Developer Cloud Node.js SDK
 ============================================
 [![Codacy Badge](https://www.codacy.com/project/badge/9d457db455d846649457bb97b6dea290)](https://www.codacy.com/app/germanattanasio/node-sdk)
 [![Build Status](https://secure.travis-ci.org/watson-developer-cloud/node-sdk.svg)](http://travis-ci.org/watson-developer-cloud/node-sdk)
@@ -12,38 +12,61 @@ Node client library to use the [Watson Developer Cloud][wdc] services, a collect
 APIs and SDKs that use cognitive computing to solve complex problems.
 
 ## Table of Contents
-  * [Watson Developer Cloud][wdc]
-    * [Installation](#installation)
-    * [Usage](#usage)
-    * [Getting the Service Credentials](#getting-the-service-credentials)
-    * [Questions](#questions)
-    * [Examples](#examples)
-    * [IBM Watson Services](#ibm-watson-services)
-      * [Alchemy Language](#alchemy-language)
-      * [Alchemy Vision](#alchemy-vision)
-      * [Alchemy Data News](#alchemy-data-news)
-      * [Authorization](#authorization)
-      * [Concept Expansion](#concept-expansion)
-      * [Concept Insights](#concept-insights)
-      * [Dialog](#dialog)
-      * [Document Conversion](#document-conversion)
-      * [Language Translation](#language-translation)
-      * [Message Resonance](#message-resonance)
-      * [Natural Language Classifier](#natural-language-classifier)
-      * [Personality Insights](#personality-insights)
-      * [Question and Answer](#question-and-answer)
-      * [Relationship Extraction](#relationship-extraction)
-      * [Speech to Text](#speech-to-text)
-      * [Text to Speech](#text-to-speech)
-      * [Tradeoff Analytics](#tradeoff-analytics)
-      * [Visual Insights](#visual-insights)
-      * [Visual Recognition](#visual-recognition)
-    * [Running in Bluemix](#running-in-bluemix)
-    * [Debug](#debug)
-    * [Tests](#tests)
-    * [Open Source @ IBM](#open-source--ibm)
-    * [License](#license)
-    * [Contributing](#contributing)
+  * [Breaking Changes for v1.0](#breaking-changes-for-v10)
+  * [Installation](#installation)
+  * [Usage](#usage)
+  * [Getting the Service Credentials](#getting-the-service-credentials)
+  * [Questions](#questions)
+  * [Examples](#examples)
+  * [IBM Watson Services](#ibm-watson-services)
+    * [Alchemy Language](#alchemy-language)
+    * [Alchemy Vision](#alchemy-vision)
+    * [Alchemy Data News](#alchemy-data-news)
+    * [Authorization](#authorization)
+    * [Concept Expansion](#concept-expansion)
+    * [Concept Insights](#concept-insights)
+    * [Dialog](#dialog)
+    * [Document Conversion](#document-conversion)
+    * [Language Translation](#language-translation)
+    * [Natural Language Classifier](#natural-language-classifier)
+    * [Personality Insights](#personality-insights)
+    * [Question and Answer](#question-and-answer)
+    * [Relationship Extraction](#relationship-extraction)
+    * [Speech to Text](#speech-to-text)
+    * [Text to Speech](#text-to-speech)
+    * [Tradeoff Analytics](#tradeoff-analytics)
+    * [Visual Insights](#visual-insights)
+    * [Visual Recognition](#visual-recognition)
+  * [Running in Bluemix](#running-in-bluemix)
+  * [Debug](#debug)
+  * [Tests](#tests)
+  * [Open Source @ IBM](#open-source--ibm)
+  * [License](#license)
+  * [Contributing](#contributing)
+
+## Breaking Changes for v1.0
+
+Several breaking changes were introduced with the v1.0.0 release:
+
+  * Experimental and Beta services now require the appropriate tag to be added to their version:
+    * Concept Expansion `v1` is now `v1-beta`
+    * Question and Answer `v1` is now `v1-beta`
+    * Relationship Extraction `v1` is now `v1-beta`
+    * Tone Analyzer `v2` is now `v2-experimental`
+    * Visual Insights `v1` is now `v1-experimental`
+    * Visual Recognition `v1` is now `v1-beta`
+  * Speech to Text gained a new `createRecognizeStream()` method replacing the existing live streaming methods with a simpler Read/Write stream.
+    The older methods are still avaliable in v1.0 but each log a deprecation warning (unless `{silent: true}` is passed in) and will be removed from a future release.
+    The affected methods are:
+    * `recognizeLive()`
+    * `observeResult()`
+    * `getRecognizeStatus()`]
+  * The Document Conversion API has been reduced to a single `convert()` method; it no longer offers batch conversion or cloud storage of files.
+  * Several deprecated services have been removed:
+    * Message Resonance
+    * Tone Analyzer v1 (replaced by v2-experimental)
+    * Search (replaced by Retrieve and Rank)
+
 
 ## Installation
 
@@ -198,7 +221,7 @@ var watson = require('watson-developer-cloud');
 var concept_expansion = watson.concept_expansion({
   username: '<username>',
   password: '<password>',
-  version: 'v1'
+  version: 'v1-beta'
 });
 
 var params = {
@@ -324,29 +347,6 @@ language_translation.identify({
 });
 ```
 
-### Message Resonance
-Get resonance information for individual words in a sentence from the
-[Message Resonance][message_resonance] service.
-
-```javascript
-var watson = require('watson-developer-cloud');
-
-var message_resonance = watson.message_resonance({
-  username: '<username>',
-  password: '<password>',
-  version:'v1'
-});
-
-message_resonance.resonance({
-  text: 'IBM Watson Developer Cloud', dataset: 1 },
-  function(err, response) {
-    if (err)
-      console.log('error:', err);
-    else
-      console.log(JSON.stringify(response, null, 2));
-});
-```
-
 ### Natural Language Classifier
 
 Use [Natural Language Classifier](http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/nl-classifier/) service to create a classifier instance by providing a set of representative strings and a set of one or more correct classes for each as training. Then use the trained classifier to classify your new question for best matching answers or to retrieve next actions for your application.
@@ -410,7 +410,7 @@ var watson = require('watson-developer-cloud');
 var question_and_answer_healthcare = watson.question_and_answer({
   username: '<username>',
   password: '<password>',
-  version: 'v1',
+  version: 'v1-beta',
   dataset: 'healthcare' /* The dataset can be specified when creating
                          * the service or when calling it */
 });
@@ -435,7 +435,7 @@ var watson = require('watson-developer-cloud');
 var relationship_extraction = watson.relationship_extraction({
   username: '<username>',
   password: '<password>',
-  version: 'v1'
+  version: 'v1-beta'
 });
 
 relationship_extraction.extract({
@@ -475,6 +475,11 @@ speech_to_text.recognize(params, function(err, res) {
   else
     console.log(JSON.stringify(res, null, 2));
 });
+
+// or streaming
+fs.createReadStream('./resources/speech.wav')
+  .pipe(speech_to_text.createRecognizeStream({ content_type: 'audio/l16; rate=44100' })
+  .pipe(fs.createWriteStream('./transcription.txt'));
 ```
 
 ### Text to Speech
@@ -493,7 +498,7 @@ var text_to_speech = watson.text_to_speech({
 
 var params = {
   text: 'Hello from IBM Watson',
-  voice: 'en-US_MichaelVoice', // Optional voice
+  voice: 'en-US_AllisonVoice', // Optional voice
   accept: 'audio/wav'
 };
 
@@ -535,7 +540,7 @@ var fs = require('fs');
 var visual_insights = watson.visual_insights({
   username: '<username>',
   password: '<password>',
-  version: 'v1'
+  version: 'v1-experimental'
 });
 
 var params = {
@@ -563,7 +568,7 @@ var fs = require('fs');
 var visual_recognition = watson.visual_recognition({
   username: '<username>',
   password: '<password>',
-  version: 'v1'
+  version: 'v1-beta'
 });
 
 var params = {
@@ -589,7 +594,7 @@ using:
 var watson = require('watson-developer-cloud');
 
 var concept_expansion = watson.concept_expansion({
-  version: 'v1',
+  version: 'v1-beta',
   use_vcap_services: false
 });
 ```
@@ -644,7 +649,6 @@ See [CONTRIBUTING](https://github.com/watson-developer-cloud/node-sdk/blob/maste
 
 
 [question_and_answer]: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/qaapi/
-[message_resonance]: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/mrapi/
 [personality_insights]: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/personality-insights/
 [concept_expansion]: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/glimpseapi/
 [relationship_extraction]: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/sireapi/

examples/concept_expansion.v1.js → examples/concept_expansion.v1-beta.js

@@ -5,7 +5,7 @@ var watson = require('watson-developer-cloud');
 var concept_expansion = watson.concept_expansion({
   username: 'INSERT YOUR USERNAME FOR THE SERVICE HERE',
   password: 'INSERT YOUR PASSWORD FOR THE SERVICE HERE',
-  version: 'v1'
+  version: 'v1-beta'
 });
 
 var params = {

examples/question_and_answer.v1.js → examples/question_and_answer.v1-beta.js

@@ -5,7 +5,7 @@ var watson = require('watson-developer-cloud');
 var question_and_answer_healthcare = watson.question_and_answer({
   username: 'INSERT YOUR USERNAME FOR THE SERVICE HERE',
   password: 'INSERT YOUR PASSWORD FOR THE SERVICE HERE',
-  version: 'v1',
+  version: 'v1-beta',
   dataset: 'healthcare' /* The dataset can be specified when creating
                          * the service or when calling it */
 });

examples/relationship_extraction.v1.js → examples/relationship_extraction.v1-beta.js

@@ -5,7 +5,7 @@ var watson = require('watson-developer-cloud');
 var relationship_extraction = watson.relationship_extraction({
   username: 'INSERT YOUR USERNAME FOR THE SERVICE HERE',
   password: 'INSERT YOUR PASSWORD FOR THE SERVICE HERE',
-  version: 'v1'
+  version: 'v1-beta'
 });
 
 relationship_extraction.extract({

examples/speech_to_text.v1.js

@@ -11,14 +11,26 @@ var speech_to_text = watson.speech_to_text({
 });
 
 var params = {
-  // From file
-  audio: fs.createReadStream('./resources/speech.wav'),
-  content_type: 'audio/l16; rate=44100'
+  content_type: 'audio/l16; rate=44100',
 };
 
-speech_to_text.recognize(params, function(err, res) {
-  if (err)
-    console.log(err);
-  else
-    console.log(JSON.stringify(res, null, 2));
-});
+// create the stream
+var recognizeStream = speech_to_text.createRecognizeStream(params);
+
+// pipe in some audio
+fs.createReadStream(__dirname + '/resources/speech.wav').pipe(recognizeStream);
+
+// and pipe out the transcription
+recognizeStream.pipe(fs.createWriteStream('transcription.txt'));
+
+
+// listen for 'data' events for just the final text
+// listen for 'results' events to get the raw JSON with interim results, timings, etc.
+
+recognizeStream.setEncoding('utf8'); // to get strings instead of Buffers from `data` events
+
+['data', 'results', 'error', 'connection-close'].forEach(function(eventName) {
+  recognizeStream.on(eventName, console.log.bind(console, eventName + ' event: '));
+});
+
+

examples/text_to_speech.v1.js

@@ -12,9 +12,9 @@ var text_to_speech = watson.text_to_speech({
 
 var params = {
   text: 'Hello from IBM Watson',
-  voice: 'en-US_MichaelVoice', // Optional voice
+  voice: 'en-US_AllisonVoice', // Optional voice
   accept: 'audio/wav'
 };
 
 // Pipe the synthesized text to a file
-text_to_speech.synthesize(params).pipe(fs.createWriteStream('output.wav'));
+text_to_speech.synthesize(params).pipe(fs.createWriteStream('output.wav'));

examples/visual_insights.v1.js → examples/visual_insights.v1-experimental.js

@@ -6,7 +6,7 @@ var fs = require('fs');
 var visual_insights = watson.visual_insights({
   username: 'INSERT YOUR USERNAME FOR THE SERVICE HERE',
   password: 'INSERT YOUR PASSWORD FOR THE SERVICE HERE',
-  version: 'v1'
+  version: 'v1-experimental'
 });
 
 var params = {

examples/visual_recognition.v1.js → examples/visual_recognition.v1-beta.js

@@ -6,7 +6,7 @@ var fs = require('fs');
 var visual_recognition = watson.visual_recognition({
   username: 'INSERT YOUR USERNAME FOR THE SERVICE HERE',
   password: 'INSERT YOUR PASSWORD FOR THE SERVICE HERE',
-  version: 'v1'
+  version: 'v1-beta'
 });
 
 var params = {

lib/alchemy_endpoints.json

@@ -90,7 +90,7 @@
 
   "image_link": {
     "url"  : "/url/URLGetImage",
-    "html" : "/url/HTMLGetImage"
+    "html" : "/html/HTMLGetImage"
   },
 
   "image_keywords": {
@@ -102,4 +102,4 @@
     "url"  : "/url/URLGetRankedImageFaceTags",
     "image" : "/image/ImageGetRankedImageFaceTags"
   }
-}
+}

lib/index.js

@@ -17,6 +17,7 @@
 'use strict';
 
 var path         = require('path');
+var fs           = require('fs');
 var util         = require('util');
 var extend       = require('extend');
 var vcapServices = require('vcap_services');
@@ -93,7 +94,29 @@ function createServiceAPI(serviceName) {
       return Object.freeze(s);
     } catch (e) {
       if (e.code === 'MODULE_NOT_FOUND') {
-        throw new Error(util.format('Service %s %s not found', serviceName, version));
+
+        // give a clear error message for services that have been sunset, with the replacement when possible
+        if (serviceName === 'search') {
+          throw new Error('The search service has been replaced by retrieve_and_rank');
+        }
+        if (serviceName === 'message_resonance') {
+          throw new Error('The message_resonance service is no longer available');
+        }
+        if (serviceName === 'tone_analyzer' && path.basename(version) === 'v1') {
+          throw new Error('tone_analyzer v1 has been replaced by v2-experimental');
+        }
+
+        // for the v1.0 breaking change of requiring experimental/beta in the module name, try to offer a helpful error message.
+        // https://github.com/watson-developer-cloud/node-sdk/issues/43
+        var msg = 'Service %s %s not found.';
+        if (fs.existsSync(path.join(__dirname, '..', 'services', serviceName, path.basename(version) + '-beta.js'))) {
+          msg += ' Did you mean ' + path.basename(version) + '-beta?';
+        }
+        if (fs.existsSync(path.join(__dirname, '..', 'services', serviceName, path.basename(version) + '-experimental.js'))) {
+          msg += ' Did you mean ' + path.basename(version) + '-experimental?';
+        }
+
+        throw new Error(util.format(msg, serviceName, version));
       } else {
         throw e;
       }
@@ -104,7 +127,6 @@ function createServiceAPI(serviceName) {
 var watson = {};
 
 [
-  'message_resonance',
   'concept_expansion',
   'question_and_answer',
   'relationship_extraction',
@@ -124,6 +146,7 @@ var watson = {};
   'visual_insights',
   // deprecated
   'search',
+  'message_resonance',
 
   // alchemy
   'alchemy_language',