api-ai-ruby 1.1.4 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a41b09d5539b73625a590a8981fc7ab84c8684de
-  data.tar.gz: f45732f184aeb2d8acc30f8d2847d3a211191bdc
+  metadata.gz: 80d81f092a618acaa74a093158d2a31df3285ad7
+  data.tar.gz: 4d37dbe4d5852cd4d0c8cf3c55cfdd117b6f11b8
 SHA512:
-  metadata.gz: 1665dcdbd43e394cb047a70f1470d65b19333595c39adc1cc3307d67f0521dc0641871614df12dc6a1bd018e0d57935099c7a03a1ad37c25caab521b08ac856d
-  data.tar.gz: 4f508ae74f7990ca232766d15aaf7f903a1c755127e82011cce5635c61b9d03f90f7084dc5985db4faea72180f9d3751cb6b2b0acc4cd87e8712aad91e0f2a8b
+  metadata.gz: f4e48a201428311e784ad7a43bb724dc9c83b35877790195d701cf4dd9c83c1f253099e60e7b0b0f099d86d0ca6210485cf534e24bda94555d8431ac1c960bfc
+  data.tar.gz: cf8f2961d2a94efe4fa1ad04af478d917b89306be8f57a1ebadbf7b88537778cec55c47efa5988841849af26d358aa88c9adeb2859685eadfabb51096685caaf

data/README.md

@@ -1,5 +1,7 @@
 # The API.AI ruby gem
 
+[![Gem Version](https://badge.fury.io/rb/api-ai-ruby.svg)](https://badge.fury.io/rb/api-ai-ruby)
+
 A Ruby SDK to the https://api.ai natural language processing service.
 
 ## Installation
@@ -62,7 +64,8 @@ ApiAiRuby::Client.new(
     client_access_token: 'YOUR_ACCESS_TOKEN',
     api_lang: 'FR',
     api_base_url: 'http://example.com/v1/',
-    api_version: 'YYYYMMDD'
+    api_version: 'YYYYMMDD',
+    api_session_id: 'some_uuid_or_whatever'
 )
 ```
 
@@ -72,14 +75,80 @@ And you also can send additional data to server during request, use second param
     response = client.text_request 'Hello', :contexts => ['firstContext'], :resetContexts => true
     response = client.voice_request file, :timezone => "America/New_York"
 ```
+
 More information about possible parameters can be found at https://docs.api.ai/docs/query page
 
+## User Entities
+
+Another possibility is to send and retrieve [custom entities](https://docs.api.ai/docs/userentities) to the server.
+
+You can do it along with **query** request
+```ruby
+client.text_request 'call Mozart', entities: [
+    {
+        name: 'contacts',
+        entries: [
+            ApiAiRuby::Entry.new('Mozart', %w(Mozart Wolfgang)),
+            ApiAiRuby::Entry.new('Salieri', %w(Salieri Antonio))
+        ]
+    }
+]
+
+# the same without ApiAiRuby::Entry wrapper
+
+client.text_request 'call Mozart', entities: [
+    {
+        name: 'contacts',
+        entries: [
+            {value: 'Mozart', synonyms: %w(Mozart Wolfgang))},
+            {value: 'Salieri', synonyms: %w(Salieri Antonio))},
+        ]
+    }
+]
+     
+```
+
+Or with separate **user_entities_request** object with full CRUD support:
+
+```ruby
+
+# preparations
+entries_composers = [
+    ApiAiRuby::Entry.new('Mozart', %w(Mozart Wolfgang)),
+    ApiAiRuby::Entry.new('Salieri', %w(Salieri Antonio))
+]
+
+entries_unknown = [
+    ApiAiRuby::Entry.new('John Doe', %w(John Unknown)),
+    ApiAiRuby::Entry.new('Jane Doe', %w(Jane))
+]
+
+entity_contacts = ApiAiRuby::Entity.new('contacts', [entries_composers])
+
+# let's go
+uer = client.user_entities_request
+uer.create(contacts) # or uer.create([entity1, entity2...])
+
+client.text_request 'call Mozart' # will work
+
+uer.update('contacts', entries_unknown)
+
+client.text_request 'call Mozart' # will NOT work
+client.text_request 'call John' # will work
+
+uer.retrieve('contacts') # will return current state of user entity
+uer.delete('contacts') # will remove user entities for given session    
+       
+```
+
+
 #Error handling
 **ApiAiRuby::Client** currently able to raise two kind of errors: **ApiAiRuby::ClientError** (due to configuration mismatch) and **ApiAiRuby::RequestError** in case of something goes wrong during request. For both kind of errors you can get **error.message** (as usual) and **ApiAiRuby::RequestError** can additionally give you code of server error (you can get it with **error.code**)
 
 
 #Changelog
 
+* 1.2.0 - added configurable session_id and separate user_entities (post) request
 * 1.1.4 - removed unused dependency and updated default API version 
 * 1.1.3 - fixed non-correctly serialized parameters in new contexts during query send process
 * 1.1.2 - fixed compatibility with ruby version less then 2.1.6

data/lib/api-ai-ruby.rb

@@ -2,7 +2,10 @@ require 'api-ai-ruby/constants'
 require 'api-ai-ruby/client'
 require 'api-ai-ruby/request_error'
 require 'api-ai-ruby/client_error'
-require 'api-ai-ruby/request_query'
-require 'api-ai-ruby/text_request'
-require 'api-ai-ruby/voice_request'
+require 'api-ai-ruby/request/request_query'
+require 'api-ai-ruby/request/text_request'
+require 'api-ai-ruby/request/voice_request'
+require 'api-ai-ruby/models/entry'
+require 'api-ai-ruby/models/entity'
+require 'api-ai-ruby/crud/user_entity_request'
 

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

@@ -1,16 +1,23 @@
+require 'securerandom'
+
 module ApiAiRuby
   class Client
     attr_accessor :client_access_token, :subscription_key
-    attr_writer :user_agent, :api_version, :api_lang, :api_base_url
+    attr_writer :user_agent, :api_version, :api_lang, :api_base_url, :api_session_id
 
     # Initializes a new Client object
     #
     # @param options [Hash]
-    # @return [Twitter::Client]
+    # @return [ApiAiRuby::Client]
     def initialize(options = {})
       options.each do |key, value|
         instance_variable_set("@#{key}", value)
       end
+
+      if !(options.key?  :api_session_id)
+        @api_session_id = SecureRandom.uuid
+      end
+
       yield(self) if block_given?
     end
 
@@ -31,6 +38,10 @@ module ApiAiRuby
       @api_version ||= ApiAiRuby::Constants::DEFAULT_API_VERSION
     end
 
+    def api_session_id
+      @api_session_id
+    end
+
     # @return [Hash]
     def credentials
       {
@@ -55,5 +66,20 @@ module ApiAiRuby
       ApiAiRuby::VoiceRequest.new(self, options).perform
     end
 
+    # @param entity_name [String]
+    # @param entries [ApiAiRuby:Entry[]]
+    # @param options [Hash]
+
+    def user_entities_request #entity_name, entries, options = {}
+      ApiAiRuby::UserEntitiesRequest.new(self);
+      # raise ApiAiRuby::ClientError.new('Entity name required') if entity_name.nil?
+      # raise ApiAiRuby::ClientError.new('Entity entries array required') if !entries.nil? && entries.is_a?(Array)
+      # raise ApiAiRuby::ClientError.new('Entity name required') if !(options.has_key?(:entries) && options[:entries].is_a?(Array))
+      # options[:name] = entity_name
+      # options[:entries] = entries
+      # options[:extend] = options[:extend] || false
+      # ApiAiRuby::UserEntitiesRequest.new(self, options).perform
+    end
+
   end
 end

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

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

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

@@ -0,0 +1,55 @@
+module ApiAiRuby
+  class UserEntitiesRequest < ApiAiRuby::RequestQuery
+
+    def initialize(client,  options = {})
+      super client, options
+      @crud_base_uri = client.api_base_url + 'userEntities'
+      @uri = @crud_base_uri
+    end
+
+
+    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')
+      end
+      @uri = @crud_base_uri
+      @request_method = :post
+      @options[:entities] = argument.is_a?(Array) ? argument : [argument]
+      response = self.perform
+      @options.delete(:entities)
+      response
+    end
+
+    def retrieve(name)
+      raise ApiAiRuby::ClientError.new('Entity name required') if !name
+      @request_method = :get
+      @uri = @crud_base_uri + '/' + name
+      self.perform
+    end
+
+    def update(name, entries, extend = false)
+
+      raise ApiAiRuby::ClientError.new('Entity name required') if !name
+
+      @options[:extend] = extend
+      @options[:name] = name
+      @options[:entries] = entries
+
+      @request_method = :put
+      @uri = @crud_base_uri + '/' + name
+      response = self.perform
+      @options.delete(:extend)
+      @options.delete(:name)
+      @options.delete(:entries)
+      response
+    end
+
+    def delete(name)
+      raise ApiAiRuby::ClientError.new('Entity name required') if !name
+      @request_method = :delete
+      @uri = @crud_base_uri + '/' + name
+      self.perform
+    end
+
+  end
+end

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

@@ -0,0 +1,24 @@
+module ApiAiRuby
+  class Entity
+    attr_accessor :name, :entries
+
+    # @param name [String]
+    # @param entries [Array]
+    def initialize (name, entries)
+      @name = name
+      @entries = entries
+    end
+
+    def to_json(*args)
+      {
+          :name => name,
+          :entries => entries
+      }.to_json(*args)
+    end
+
+    def addEntry(value, synonyms)
+      @entries.push new ApiAiRuby::Entry(value, synonyms)
+    end
+
+  end
+end

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

@@ -0,0 +1,19 @@
+module ApiAiRuby
+  class Entry
+    attr_accessor :value, :synonyms
+
+    # @param value [String]
+    # @param synonyms [Array]
+    def initialize (value, synonyms)
+      @value = value
+      @synonyms = synonyms
+    end
+
+    def to_json(*args)
+      {
+          :value => @value,
+          :synonyms => @synonyms
+      }.to_json(*args)
+    end
+  end
+end

data/lib/api-ai-ruby/{request_query.rb → request/request_query.rb}

@@ -13,7 +13,7 @@ module ApiAiRuby
       @client = client
       @uri = client.api_base_url + 'query?v=' + client.api_version
       @request_method = :post
-      options[:lang] = client.api_lang
+      options[:sessionId] = client.api_session_id
       @options = options
       @headers = {
           Authorization: 'Bearer ' + client.client_access_token,
@@ -22,7 +22,13 @@ module ApiAiRuby
 
     # @return [Array, Hash]
     def perform
-      options_key = @options.has_key?(:voiceData) ? :form : :json
+
+      if @options.has_key?(:voiceData)
+        options_key = :form
+      else
+        options_key = (@request_method === :get) ? :params : :json
+      end
+
       response = HTTP.with(@headers).public_send(@request_method, @uri.to_s, options_key => @options)
       response_body = symbolize_keys!(response.parse)
       response_headers = response.headers
@@ -34,7 +40,7 @@ module ApiAiRuby
 
     def fail_or_return_response_body(code, body)
       error = false
-      if code != 200 || body[:status][:code] != 200
+      if code != 200 || (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/lib/api-ai-ruby/{text_request.rb → request/text_request.rb}

@@ -1,6 +1,7 @@
 module ApiAiRuby
   class TextRequest < ApiAiRuby::RequestQuery
     def initialize (client, options={})
+      options[:lang] = client.api_lang
       super client, options
     end
   end

data/lib/api-ai-ruby/{voice_request.rb → request/voice_request.rb}

@@ -8,8 +8,8 @@ module ApiAiRuby
     # @param options [Hash]
     # @return [ApiAiRuby::VoiceRequest]
     def initialize(client,  options = {})
+      options[:lang] = client.api_lang
       super client, options
-
       file = options.delete(:file)
       options = {
           :request => options.to_json,

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

@@ -1,27 +1,30 @@
 require 'helper'
 
 describe 'api' do
-  let (:client) { ApiAiRuby::Client.new(:client_access_token => '3485a96fb27744db83e78b8c4bc9e7b7')}
+  before(:all) { @client = ApiAiRuby::Client.new(
+      :client_access_token => '3485a96fb27744db83e78b8c4bc9e7b7',
+      :api_session_id => 'testsession'
+  )}
 
   it 'should return response' do
-    response = client.text_request 'Hello'
+    response = @client.text_request 'Hello'
     expect(response[:result][:resolvedQuery]).to eq 'Hello'
     expect(response[:result][:action]).to eq 'greeting'
   end
 
   it 'should use input contexts' do
-    response = client.text_request 'Hello', :resetContexts => true
+    response = @client.text_request 'Hello', :resetContexts => true
     expect(response[:result][:action]).to eq 'greeting'
 
-    response = client.text_request 'Hello', :contexts => ['firstContext'], :resetContexts => true
+    response = @client.text_request 'Hello', :contexts => ['firstContext'], :resetContexts => true
     expect(response[:result][:action]).to eq 'firstGreeting'
 
-    response = client.text_request 'Hello', :contexts => ['secondContext'], :resetContexts => true
+    response = @client.text_request 'Hello', :contexts => ['secondContext'], :resetContexts => true
     expect(response[:result][:action]).to eq 'secondGreeting'
   end
 
   it 'should return output contexts' do
-    response = client.text_request 'weather', :resetContexts => true
+    response = @client.text_request 'weather', :resetContexts => true
     expect(response[:result][:action]).to eq 'showWeather'
     expect(response[:result][:contexts]).not_to be_nil
     expect(response[:result][:contexts].any? {|context| context[:name] == 'weather'}).to be true
@@ -33,15 +36,70 @@ 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'
   end
 
   it 'should correctly set contexts with parameters' do
-    client.text_request 'Hello', :resetContexts => true
-    response = client.text_request 'hello', contexts: [{ name: 'user', parameters: { first_name: 'Johnny' }}]
+    @client.text_request 'Hello', :resetContexts => true
+    response = @client.text_request 'hello', contexts: [{ name: 'user', parameters: { first_name: 'Johnny' }}]
     expect(response[:result][:contexts]).not_to be_nil
     expect(response[:result][:contexts][0][:name]).to eq 'user'
     expect(response[:result][:contexts][0][:parameters][:first_name]).to eq 'Johnny'
   end
 
+  it 'should use custom entities' do
+    response = @client.text_request 'hi nori', entities: [
+        {
+            name: 'dwarfs',
+            entries: [
+                ApiAiRuby::Entry.new('Ori', %w(ori Nori)),
+                {value: 'bifur', synonyms: %w(Bofur Bombur)}
+            ]
+        }
+    ]
+
+    expect(response[:result][:action]).to eq 'say_hi'
+    expect(response[:result][:fulfillment][:speech]). to eq 'hi Bilbo, I am Ori'
+  end
+
+  describe 'userEntities endpoint' do
+
+    before(:all) { @uer = @client.user_entities_request}
+
+    let(:entity1) {
+      ApiAiRuby::Entity.new 'dwarfs', [ApiAiRuby::Entry.new('giur', %w(Giur Amaldur))]
+    }
+
+    let(:entries) {
+      [ApiAiRuby::Entry.new('mami', %w(Mami Nami))]
+    }
+
+    it 'should create custom entities through separate request' do
+      @uer.create(entity1)
+      response = @client.text_request 'hi Amaldur'
+      expect(response[:result][:action]).to eq 'say_hi'
+      expect(response[:result][:fulfillment][:speech]). to eq 'hi Bilbo, I am giur'
+    end
+
+    it 'should update custom entities through separate request' do
+      @uer.update('dwarfs', entries)
+      response = @client.text_request 'hi Nami'
+      expect(response[:result][:action]).to eq 'say_hi'
+      expect(response[:result][:fulfillment][:speech]). to eq 'hi Bilbo, I am mami'
+    end
+
+    it 'should retrieve custom enitities' do
+      response = @uer.retrieve('dwarfs')
+      expect(response[:name]).to eq 'dwarfs'
+      expect(response[:entries][0][:value]).to eq 'mami'
+    end
+
+    it 'should remove custom entities' do
+      @uer.delete('dwarfs')
+      expect{@uer.retrieve('dwarfs')}.to raise_error(ApiAiRuby::RequestError)
+    end
+
+  end
+
+
 end

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

@@ -38,13 +38,23 @@ describe ApiAiRuby::Client do
       expect(client.api_base_url).to eq ApiAiRuby::Constants::DEFAULT_BASE_URL
       expect(client.api_version).to eq ApiAiRuby::Constants::DEFAULT_API_VERSION
       expect(client.api_lang).to eq ApiAiRuby::Constants::DEFAULT_CLIENT_LANG
+      expect(client.api_session_id).to be_a(String)
     end
 
     it 'correctly creates client with given properties' do
-      client = ApiAiRuby::Client.new(subscription_key: 'SK', client_access_token: 'CS', api_lang: 'RU', api_base_url: 'http://localhost', api_version: '1234')
+      client = ApiAiRuby::Client.new(
+          subscription_key: 'SK',
+          client_access_token: 'CS',
+          api_lang: 'RU',
+          api_base_url: 'http://localhost',
+          api_version: '1234',
+          api_session_id: '555'
+      )
+
       expect(client.api_base_url).to eq 'http://localhost'
       expect(client.api_version).to eq '1234'
       expect(client.api_lang).to eq 'RU'
+      expect(client.api_session_id).to eq '555'
     end
 
 

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

@@ -0,0 +1,8 @@
+require 'helper'
+
+describe ApiAiRuby::Client do
+
+  # let (:client) { ApiAiRuby::Client.new(:client_access_token => 'CS')}
+  # @todo: add configuration tests
+
+end

data/spec/helper.rb

@@ -6,7 +6,7 @@ SimpleCov.formatters = [SimpleCov::Formatter::HTMLFormatter, Coveralls::SimpleCo
 SimpleCov.start do
   add_filter '/spec/'
   add_filter '/vendor/'
-  minimum_coverage(99.57)
+  minimum_coverage(95)
 end
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api-ai-ruby
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.2.0
 platform: ruby
 authors:
 - api.ai
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-02 00:00:00.000000000 Z
+date: 2016-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -70,14 +70,18 @@ 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/user_entity_request.rb
+- lib/api-ai-ruby/models/entity.rb
+- lib/api-ai-ruby/models/entry.rb
+- lib/api-ai-ruby/request/request_query.rb
+- lib/api-ai-ruby/request/text_request.rb
+- lib/api-ai-ruby/request/voice_request.rb
 - lib/api-ai-ruby/request_error.rb
-- lib/api-ai-ruby/request_query.rb
-- lib/api-ai-ruby/text_request.rb
-- lib/api-ai-ruby/voice_request.rb
 - spec/api-ai-ruby/api_spec.rb
 - spec/api-ai-ruby/client_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
@@ -110,6 +114,7 @@ test_files:
 - spec/api-ai-ruby/client_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