api-ai-ruby 1.2.3 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 730482838f5570e11f15f9dc035bd1660dcc9ee6
-  data.tar.gz: 50f4c68548a98f9055f01e8196f5bb1cea2931ef
+  metadata.gz: 00c4d8ce3cf45b523509982821303403e1dc26c4
+  data.tar.gz: 18107f16fe11ea0477c3b0b9797fe2c5164630b6
 SHA512:
-  metadata.gz: ec864af3471a6f93aa1bb898e7fc29ed341b4dfb4828da406beb2570538bcd3f21b71755fdd3eb66822bda1a1e5baac3ae6e6ba866a24957eeee16903504f238
-  data.tar.gz: 9d1548277b2bb7a98b5f11bb789f91d80d050bfa3d9b7dad7fd29da6a63c87d2a48d3833648c594358124b623185cee0e87d5a0e68d2546c7cc2bc1d2dc9a53c
+  metadata.gz: f3ce511381bc5c787c68dcd87da8ae0fa5eb65c6a0b64cf822a54218810c818a8fab23ba6bbf8a66bc2993085f2faee649f3ce7bb20a02b5d6dce1a5f9d3268b
+  data.tar.gz: b5ec12321765aaf92ebb7f764a4c737ae92fb916f20a6d52e15736aaf3b225fc028d1159b223b35dd01d295dd21e99e48df037ad131d905acef55f15545fec17

data/README.md

@@ -79,15 +79,15 @@ client.text_request 'call Mozart', entities: [
     {
         name: 'contacts',
         entries: [
-            {value: 'Mozart', synonyms: %w(Mozart Wolfgang))},
-            {value: 'Salieri', synonyms: %w(Salieri Antonio))},
+            {value: 'Mozart', synonyms: %w(Mozart Wolfgang)},
+            {value: 'Salieri', synonyms: %w(Salieri Antonio)}
         ]
     }
 ]
      
 ```
 
-Or with separate **user_entities_request** object with full CRUD support:
+Or with separate **create_user_entities_request** object with full CRUD support:
 
 ```ruby
 
@@ -105,7 +105,7 @@ entries_unknown = [
 entity_contacts = ApiAiRuby::Entity.new('contacts', [entries_composers])
 
 # let's go
-uer = client.user_entities_request
+uer = client.create_user_entities_request
 uer.create(contacts) # or uer.create([entity1, entity2...])
 
 client.text_request 'call Mozart' # will work
@@ -119,6 +119,40 @@ uer.retrieve('contacts') # will return current state of user entity
 uer.delete('contacts') # will remove user entities for given session    
        
 ```
+## Context
+Also SDK has full support of [contexts](https://docs.api.ai/docs/contexts) API.AI endpoint with special object, called ```contexts_request```
+Usage is simple:
+```ruby
+
+# some preparations
+lifespan = 5
+parameters = {
+  :param_name => 'param_value'
+}
+name = 'test_context'
+
+# you can create context using built-in model ApiAiRuby::Context 
+test_context = ApiAiRuby::Context.new(name, lifespan, parameters)
+another_test_context = ApiAiRuby::Context.new('another_test_context')
+one_more_test_context = ApiAiRuby::Context.new('one_more_test_context', 4)
+
+# ok, we are ready
+
+context_request = @client.create_contexts_request
+
+# there are different options to be used with .create
+
+context_request.create(test_context)
+context_request.create([another_test_context, one_more_test_context])
+context_request.create('one_more_super_final_mega_context')
+
+context_request.retrieve('test_context') # will return you single context or nothing
+context_request.list() # will return you list of all contexts used in current session
+context_request.delete('test_context') # will remove single context
+context_request.delete() # will remove all context in session
+
+```
+
 #Timeouts
 **ApiAiRuby::Client** uses the [http gem](https://github.com/httprb/http) under the hood.  You can use ```timeout_options``` on the client to set these.
 ```ruby
@@ -141,6 +175,15 @@ Please see the [httprb wiki on timeouts](https://github.com/httprb/http/wiki/Tim
 
 #Changelog
 
+##1.3.0 
+###Non-breaking
+- contexts endpoint support (https://docs.api.ai/docs/contexts)
+- better RDoc
+###Breaking
+- ApiAiRuby::Client::user_entities_request renamed to ApiAiRuby::Client::create_user_entities_request
+- ApiAiRuby::Entity::addEntry renamed to ApiAiRuby::Entity::add_entry
+
+##Previous
 * 1.2.3 - events support
 * 1.2.2 - added configurable timeouts for requests (thanks [bramski](https://github.com/bramski))
 * 1.2.1 - fixed UTF-8 in text-requests

data/lib/api-ai-ruby.rb

@@ -6,6 +6,8 @@ require 'api-ai-ruby/request/request_query'
 require 'api-ai-ruby/request/text_request'
 require 'api-ai-ruby/request/event_request'
 require 'api-ai-ruby/request/voice_request'
+require 'api-ai-ruby/models/context'
 require 'api-ai-ruby/models/entry'
 require 'api-ai-ruby/models/entity'
+require 'api-ai-ruby/crud/contexts_request'
 require 'api-ai-ruby/crud/user_entity_request'

data/lib/api-ai-ruby/client.rb

@@ -2,6 +2,7 @@ require 'securerandom'
 
 module ApiAiRuby
   class Client
+
     attr_accessor :client_access_token, :timeout_options
     attr_writer :user_agent, :api_version, :api_lang, :api_base_url, :api_session_id
 
@@ -25,18 +26,22 @@ module ApiAiRuby
       @user_agent ||= "ApiAiRubyGem/#{ApiAiRuby::Constants::VERSION}"
     end
 
+    # @return [String]
     def api_base_url
       @api_base_url ||= ApiAiRuby::Constants::DEFAULT_BASE_URL
     end
 
+    # @return [String]
     def api_lang
       @api_lang ||= ApiAiRuby::Constants::DEFAULT_CLIENT_LANG
     end
 
+    # @return [String]
     def api_version
       @api_version ||= ApiAiRuby::Constants::DEFAULT_API_VERSION
     end
 
+    # @return [String]
     def api_session_id
       @api_session_id
     end
@@ -59,27 +64,38 @@ module ApiAiRuby
       ApiAiRuby::TextRequest.new(self, options).perform
     end
 
-    # @param eventName [String]
-    # @param data [Object]
-    # @param options [Object]
-    def event_request (eventName = '', data = {}, options = {})
+    # @param event_name [String]
+    # @param data [Hash]
+    # @param options [Hash]
+    # @return [Hash]
+    def event_request (event_name = '', data = {}, options = {})
       raise ApiAiRuby::ClientError.new('Credentials missing') if !credentials?
       options[:event] = {
-          name: eventName,
+          name: event_name,
           data: data
       }
       ApiAiRuby::EventRequest.new(self, options).perform
     end
 
+    # @deprecated
+    # @param file_stream [File]
+    # @param options [Object]
+    # @return [Array, Hash]
     def voice_request(file_stream, options = {})
       raise ApiAiRuby::ClientError.new('Credentials missing') if !credentials?
       options[:file] = file_stream
       ApiAiRuby::VoiceRequest.new(self, options).perform
     end
 
-    def user_entities_request
+    # @return [ApiAiRuby::UserEntitiesRequest]
+    def create_user_entities_request
       ApiAiRuby::UserEntitiesRequest.new(self);
     end
 
+    # @return [ApiAiRuby::ContextsRequest]
+    def create_contexts_request
+      ApiAiRuby::ContextsRequest.new(self)
+    end
+
   end
 end

data/lib/api-ai-ruby/constants.rb

@@ -1,6 +1,6 @@
 module ApiAiRuby
   class Constants
-    VERSION = '1.2.3'
+    VERSION = '1.3.0'
     DEFAULT_BASE_URL = 'https://api.api.ai/v1/'
     DEFAULT_API_VERSION = '20150910'
     DEFAULT_CLIENT_LANG = 'en'

data/lib/api-ai-ruby/crud/contexts_request.rb

@@ -0,0 +1,54 @@
+module ApiAiRuby
+  class ContextsRequest < ApiAiRuby::RequestQuery
+
+    def initialize(client,  options = {})
+      super client, options
+      @headers['Content-Type'] = 'application/json; charset=UTF-8'
+      @crud_base_uri = client.api_base_url + 'contexts'
+      @uri = @crud_base_uri
+    end
+
+    # @param name [String]
+    # @return [ApiAiRuby::Context]
+    def retrieve(name)
+      raise ApiAiRuby::ClientError.new('context name required') if !name
+      @request_method = :get
+      @options = nil
+      @uri = @crud_base_uri + '/' + name + '?sessionId=' + self.client.api_session_id
+      self.perform
+    end
+
+    # @return [Array<ApiAiRuby::Context>]
+    def list
+      @request_method = :get
+      @uri = @crud_base_uri + '?sessionId=' + self.client.api_session_id
+      @options = nil
+      self.perform
+    end
+
+    # @param context [Array<ApiAiRuby::Context>, ApiAiRuby::Context, String]
+    def create(contexts)
+
+      @request_method = :post
+      @uri = @crud_base_uri + '?sessionId=' + self.client.api_session_id
+
+      @options = nil
+      @options = contexts if contexts.is_a? Array
+      @options = [contexts] if contexts.is_a? ApiAiRuby::Context
+      @options = [{:name => contexts}] if contexts.is_a? String
+      raise ApiAiRuby::ClientError.new(
+          'You should pass instance of ApiAiRuby::Context, Array<ApiAiRuby::Context> or String to ContextsRequest::create ') if @options == nil
+      self.perform
+    end
+
+    def delete(name = nil)
+      @request_method = :delete
+      @options = nil
+      @uri = @crud_base_uri + '?sessionId=' + self.client.api_session_id
+      @uri = @crud_base_uri + '/' + name + '?sessionId=' + self.client.api_session_id if name != nil
+      # @options[:sessionId] = self.client.api_session_id
+      self.perform
+    end
+
+  end
+end

data/lib/api-ai-ruby/crud/user_entity_request.rb

@@ -8,7 +8,8 @@ module ApiAiRuby
       @uri = @crud_base_uri
     end
 
-
+    # @param argument [Array<ApiAiRuby::Entity, Hash>, ApiAiRuby::Entity, Hash]
+    # @return [Hash]
     def create(argument)
       if !(argument && (argument.is_a?(Array) || argument.is_a?(Hash) || argument.is_a?(ApiAiRuby::Entity)))
         raise ApiAiRuby::ClientError.new('Argument should be array of Entities or single Entity object')

data/lib/api-ai-ruby/models/context.rb

@@ -0,0 +1,23 @@
+module ApiAiRuby
+  class Context
+    attr_accessor :name, :lifespan, :parameters
+
+    # @param name [String]
+    # @param lifespan [Numeric]
+    # @param parameters [Hash]
+    def initialize (name, lifespan = 5, parameters = {})
+      @name = name
+      @lifespan = lifespan
+      @parameters = parameters
+    end
+
+    def to_json(*args)
+      {
+          :name => name,
+          :lifespan => lifespan,
+          :parameters => parameters
+      }.to_json(*args)
+    end
+
+  end
+end

data/lib/api-ai-ruby/models/entity.rb

@@ -3,7 +3,7 @@ module ApiAiRuby
     attr_accessor :name, :entries
 
     # @param name [String]
-    # @param entries [Array]
+    # @param entries [Array<ApiAiRuby::Entry, Hash>]
     def initialize (name, entries)
       @name = name
       @entries = entries
@@ -16,7 +16,7 @@ module ApiAiRuby
       }.to_json(*args)
     end
 
-    def addEntry(value, synonyms)
+    def add_entry(value, synonyms)
       @entries.push new ApiAiRuby::Entry(value, synonyms)
     end
 

data/lib/api-ai-ruby/request/request_query.rb

@@ -21,9 +21,9 @@ module ApiAiRuby
       @timeout_options = client.timeout_options || options[:timeout_options]
     end
 
-    # @return [Array, Hash]
+    # @return [Hash]
     def perform
-      if @options.has_key?(:voiceData)
+      if @options && @options.is_a?(Hash) && @options.has_key?(:voiceData)
         options_key = :form
       else
         options_key = (@request_method === :get) ? :params : :json
@@ -31,17 +31,17 @@ module ApiAiRuby
 
       request = HTTP.with(@headers)
       request = request.timeout(*@timeout_options) if @timeout_options
-      response = request.public_send(@request_method, @uri.to_s, options_key => @options)
+      response = request.public_send(@request_method, @uri.to_s, options_key => @options) if @options
+      response = request.public_send(@request_method, @uri.to_s) if @options == nil
       response_body = symbolize_keys!(response.parse)
       fail_or_return_response_body(response.code, response_body)
     end
 
     private
 
-
     def fail_or_return_response_body(code, body)
       error = false
-      if code != 200 || (body[:status] && body[:status][:code] && body[:status][:code] != 200)
+      if code != 200 || (body.is_a?(Hash) && body[:status] && body[:status][:code] && body[:status][:code] != 200)
         error = ApiAiRuby::RequestError.new body[:status][:errorDetails], body[:status][:code]
       end
       fail(error) if error

data/spec/api-ai-ruby/api_spec.rb

@@ -1,10 +1,12 @@
 require 'helper'
 
 describe 'api' do
-  before(:all) { @client = ApiAiRuby::Client.new(
+  before(:all) {
+    @client = ApiAiRuby::Client.new(
       :client_access_token => '3485a96fb27744db83e78b8c4bc9e7b7',
       :api_session_id => 'testsession'
-  )}
+    )
+  }
 
   it 'should return response' do
     response = @client.text_request 'Hello'
@@ -40,9 +42,9 @@ describe 'api' do
   end
 
   it 'should send voiceData to API' do
-    # expect(@client.voice_request(File.new(fixture_path + '/hello.wav'))[:result][:resolvedQuery]).to eq 'hello'
+    expect(@client.voice_request(File.new(fixture_path + '/hello.wav'))[:result][:resolvedQuery]).to eq 'hello'
     # asr was disabled for non-premium users
-    expect {@client.voice_request(File.new(fixture_path + '/hello.wav'))}.to raise_error(ApiAiRuby::RequestError)
+    # expect {@client.voice_request(File.new(fixture_path + '/hello.wav'))}.to raise_error(ApiAiRuby::RequestError)
   end
 
   it 'should correctly set contexts with parameters' do
@@ -70,7 +72,7 @@ describe 'api' do
 
   describe 'userEntities endpoint' do
 
-    before(:all) { @uer = @client.user_entities_request}
+    before(:all) { @uer = @client.create_user_entities_request}
 
     let(:entity1) {
       ApiAiRuby::Entity.new 'dwarfs', [ApiAiRuby::Entry.new('giur', %w(Giur Amaldur))]
@@ -115,4 +117,40 @@ describe 'api' do
     # end
 
   end
+
+  describe 'contexts endpoint' do
+
+    before(:all) { @context_request = @client.create_contexts_request}
+
+    it 'should retrieve contexts' do
+      @client.text_request 'Hello', :contexts =>  %w(firstContext secondContext), :resetContexts => true
+      response = @context_request.list
+      expect(response[0][:name]).to eq 'secondcontext'
+      expect(response[1][:name]).to eq 'firstcontext'
+    end
+
+    it 'should retrieve contexts by name' do
+      response = @context_request.retrieve 'secondContext'
+      expect(response[:name]).to eq 'secondcontext'
+    end
+
+    it 'should delete all curret contexts' do
+      @context_request.delete
+      expect(@context_request.list.length).to be 0
+    end
+
+    it 'should create context via crud' do
+      @context_request.create('test')
+      @context_request.create(ApiAiRuby::Context.new('test1'))
+      @context_request.create([ApiAiRuby::Context.new('test2'), ApiAiRuby::Context.new('test3',)])
+      expect(@context_request.list.length).to be 4
+    end
+
+    it 'should delete context by name' do
+      @context_request.delete('test3')
+      expect(@context_request.list.length).to be 3
+    end
+
+  end
+
 end

data/spec/api-ai-ruby/context_request_spec.rb

@@ -0,0 +1 @@
+# @todo: write unit-tests

data/spec/api-ai-ruby/voice_request_spec.rb

@@ -0,0 +1 @@
+# @todo: write unit-tests

metadata

@@ -1,55 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: api-ai-ruby
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.3.0
 platform: ruby
 authors:
 - api.ai
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-05 00:00:00.000000000 Z
+date: 2017-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: http
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.9.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.9.4
 description: Plugin makes it easy to integrate your Ruby application with https://api.ai
@@ -60,7 +60,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
+- .gitignore
 - Gemfile
 - LICENSE
 - README.md
@@ -70,7 +70,9 @@ files:
 - lib/api-ai-ruby/client.rb
 - lib/api-ai-ruby/client_error.rb
 - lib/api-ai-ruby/constants.rb
+- lib/api-ai-ruby/crud/contexts_request.rb
 - lib/api-ai-ruby/crud/user_entity_request.rb
+- lib/api-ai-ruby/models/context.rb
 - lib/api-ai-ruby/models/entity.rb
 - lib/api-ai-ruby/models/entry.rb
 - lib/api-ai-ruby/request/event_request.rb
@@ -80,6 +82,7 @@ files:
 - lib/api-ai-ruby/request_error.rb
 - spec/api-ai-ruby/api_spec.rb
 - spec/api-ai-ruby/client_spec.rb
+- spec/api-ai-ruby/context_request_spec.rb
 - spec/api-ai-ruby/error_spec.rb
 - spec/api-ai-ruby/text_request_spec.rb
 - spec/api-ai-ruby/user_entities_request_spec.rb
@@ -96,26 +99,28 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ~>
     - !ruby/object:Gem::Version
       version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.0.14.1
 signing_key: 
 specification_version: 4
 summary: ruby SDK for https://api.ai
 test_files:
 - spec/api-ai-ruby/api_spec.rb
 - spec/api-ai-ruby/client_spec.rb
+- spec/api-ai-ruby/context_request_spec.rb
 - spec/api-ai-ruby/error_spec.rb
 - spec/api-ai-ruby/text_request_spec.rb
 - spec/api-ai-ruby/user_entities_request_spec.rb
 - spec/api-ai-ruby/voice_request_spec.rb
 - spec/fixtures/hello.wav
 - spec/helper.rb
+has_rdoc: