API docs + better error message

Author: patapizza

CHANGES.md

@@ -1,3 +1,8 @@
+## v3.1
+
+- allows for custom logging
+- better error message
+
 ## v3.0
 
 Bot Engine integration

README.md

@@ -20,23 +20,111 @@ gem install wit-*.gem
 
 See the `examples` folder for examples.
 
+## API
+
+### Overview
+
+`wit-ruby` provides a Wit class with the following methods:
+* `message` - the Wit [message API](https://wit.ai/docs/http/20160330#get-intent-via-text-link)
+* `converse` - the low-level Wit [converse API](https://wit.ai/docs/http/20160330#converse-link)
+* `run_actions` - a higher-level method to the Wit converse API
+
+### Wit class
+
+The Wit constructor takes the following parameters:
+* `access_token` - the access token of your Wit instance
+* `actions` - the `Hash` with your actions
+
+The `actions` `Hash` has action names as keys, and action implementations as values.
+Action names are symbols, and action implementations are lambda functions (not `Proc`).
+You need to provide at least an implementation for the special actions `:say`, `:merge` and `:error`.
+
+A minimal `actions` `Hash` looks like this:
+```ruby
+actions = {
+  :say => -> (session_id, msg) {
+    p msg
+  },
+  :merge => -> (context, entities) {
+    return context
+  },
+  :error => -> (session_id, msg) {
+    p 'Oops I don\'t know what to do.'
+  },
+}
+```
+
+A custom action takes one parameter:
+* `context` - the `Hash` representing the session state
+
+Example:
+```ruby
+require 'wit'
+client = Wit.new access_token, actions
+```
+
 ### Logging
 
-Default logging is to `STDOUT` with `INFO` level. Silence logger as follows.
+Default logging is to `STDOUT` with `INFO` level.
 
+You can setup your logging level as follows:
 ```ruby
 Wit.logger.level = Logger::WARN
 ```
+See the [Logger class](http://ruby-doc.org/stdlib-2.1.0/libdoc/logger/rdoc/Logger.html) docs for more information.
 
-## API
+### message
+
+The Wit [message API](https://wit.ai/docs/http/20160330#get-intent-via-text-link).
+
+Takes the following parameters:
+* `msg` - the text you want Wit.ai to extract the information from
+
+Example:
+```ruby
+resp = client.message 'what is the weather in London?'
+p "Yay, got Wit.ai response: #{resp}"
+```
+
+### run_actions
+
+A higher-level method to the Wit converse API.
+
+Takes the following parameters:
+* `session_id` - a unique identifier describing the user session
+* `message` - the text received from the user
+* `context` - the `Hash` representing the session state
+* `max_steps` - (optional) the maximum number of actions to execute (defaults to 5)
+
+Example:
+```ruby
+session = 'my-user-session-42'
+context0 = {}
+context1 = client.run_actions session, 'what is the weather in London?', context0
+p "The session state is now: #{context1}"
+context2 = client.run_actions session, 'and in Brussels?', context1
+p "The session state is now: #{context2}"
+```
+
+### converse
+
+The low-level Wit [converse API](https://wit.ai/docs/http/20160330#converse-link).
+
+Takes the following parameters:
+* `session_id` - a unique identifier describing the user session
+* `msg` - the text received from the user
+* `context` - the `Hash` representing the session state
+
+Example:
+```ruby
+resp = client.converse 'my-user-session-42', 'what is the weather in London?', {}
+p "Yay, got Wit.ai response: #{resp}"
+```
 
-`wit-ruby` provides a Wit class with the following methods:
-* `message` - the Wit message API
-* `converse` - the low-level Wit converse API
-* `run_actions` - a higher-level method to the Wit converse API
 
 See the [docs](https://wit.ai/docs) for more information.
 
+
 ## Thanks
 
 Thanks to [Justin Workman](http://github.com/xtagon) for releasing a first version in October 2013. We really appreciate!

lib/wit.rb

@@ -21,7 +21,9 @@ def req(access_token, meth_class, path, params={}, payload={})
   Net::HTTP.start uri.host, uri.port, {:use_ssl => uri.scheme == 'https'} do |http|
     rsp = http.request request
     raise WitException.new "HTTP error code=#{rsp.code}" unless rsp.code.to_i <= 200
-    JSON.parse rsp.body
+    json = JSON.parse rsp.body
+    raise WitException.new "Wit responded with an error: #{json['error']}" if json.has_key? 'error'
+    json
   end
 end
 

wit.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'wit'
-  s.version = '3.0.0'
+  s.version = '3.1.0'
   s.date = '2014-12-05'
   s.summary = 'Ruby SDK for Wit.ai'
   s.description = 'Ruby SDK for Wit.ai'