amorail 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 151952934c801a5cce9b699869f1e46bd88f4e6a
-  data.tar.gz: 9ed39010c5f080bd68c07d35fc3434edba549b4d
+  metadata.gz: 7d135728d3ff91d041ff0114f7674f548758ede9
+  data.tar.gz: 66c9aef842b6989ceb4eca793358e9d6c61140ca
 SHA512:
-  metadata.gz: a11232b9fbc2f0b93f87d90e14c8ac068dff7281e732727156229708e3cb8bb0f1406840922ad203f41cbd451bd0d926e75d46c1c37a3f2893ff20a65d100069
-  data.tar.gz: 0eba066877b078d2676e0c9896b5c36a6a9451cf5894c4cabe0b83377c2d65b528970e8bc5bfc2cdd7e2185d789136fb8db8ce0faa2034181b624bd03997dce8
+  metadata.gz: 9bb9ea6019c46ce4ec6778abbc45d6d1c1c7dee9fe99177ab9a7753b810d7a6495c9f813eab700309b17e9f3e85bf7af359d4b1e798c09d5355244a3aadb2377
+  data.tar.gz: 2671b2d09412cda7bba66d90961a474fad00848a39e004cf22f6ecb76821e98412966151158f855caee92631ed8dd31ff56217ac4e003d9836cdb7649a91f9f7

data/README.md

@@ -22,7 +22,143 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+With Amorail you can manipulate the following AmoCRM entities: Companies, Contacts, Leads and Tasks.
+We're triying to build simple AR-like interface.
+
+### Auth configuration
+
+Amorail uses [anyway_config](https://github.com/palkan/anyway_config) for configuration, so you
+can provide configuration parameters through env vars, seperate config file (`config/amorail.yml`) or `secrets.yml`.
+
+Required params: **usermail**, **api_key** and **api_endpoint**.
+
+Example:
+
+```
+# config/secrets.yml
+development:
+  ...
+  amorail:
+    usermail: 'amorail@test.com'
+    api_key: '75742b166417fe32ae132282ce178cf6'
+    api_endpoint: 'https://test.amocrm.ru'
+```
+
+### Running from console
+
+You can try amorail in action from console ([PRY](https://github.com/pry/pry) is required to be installed):
+
+```shell
+# amorail gem directory
+AMORAIL_USERMAIL=my_mail@test.com AMORAIL_API_KEY=my_key AMORAIL_API_ENDPOINT=my@amo.com bundle exec rake console
+pry> Amorail.properties
+# ... prints properties (custom_fields) data
+pry> Amorail::Contact.find_by_query("test_contact")
+# ... returns array of contacts which satisfy the query  
+```
+
+### Create new objects
+
+Create Leads
+
+```ruby
+lead = Amorail::Lead.new(
+  name:  "Example Lead",
+  tags: "IT, Sales",
+  price: 100,
+  status_id: Amorail.properties.leads.statuses[
+    Rails.application.secrets.amoparams['lead_status']
+  ].id
+)
+
+lead.save!
+```
+
+Create Company
+
+```ruby
+company = Amorail::Company.new(
+  name: "My company",
+  phone: "222-111",
+  email: "human@example.com"
+)
+company.linked_leads_id << lead.id
+company.save!
+```
+
+Create Contact
+
+```ruby
+contact = Amorail::Contact.new(
+  name: "Ivan Ivanov",
+  linked_company_id: company.id,
+  phone: "111-222",
+  email: "ivan@example.com"
+)
+
+contact.linked_leads_id << lead.id
+contact.save!
+```
+
+Create Task
+
+```ruby
+task = Amorail::Task.new(
+  text: "Example task",
+  lead: true,
+  complete_till: Time.zone.today.end_of_day,
+  task_type: Amorail.properties.tasks[Rails.application.secrets.amoparams['task_code']].id
+)
+
+# set up lead id
+task.element_id = lead.id
+# and save it
+task.save!
+```
+
+You can find any object by id:
+
+```ruby
+  Amorail::Company.find(company_id)
+```
+
+Or using query:
+
+```ruby
+  Amorail::Company.find_by_query("vip")
+```
+
+Also you can update objects, e.g:
+
+```ruby
+company = Amorail::Company.find(company_id)
+contact = Amorail::Contact.find(contact_id)
+
+# like this
+contact.linked_company_id = company.id
+contact.save!
+
+# or
+
+contact.update(linked_company_id: company.id)
+```
+
+
+### Properties Configuration
+
+AmoCRM is using "custom_fields" architecture,
+to get all information for your account, you can
+find properties and set up configuration manually in config/secrets.yml.
+
+Note: response example in official documentation: 
+      https://developers.amocrm.ru/rest_api/accounts_current.php
+
+1) Get list of properties for your account
+
+```
+rake amorail:check
+```
+Rake task will returns information about properties.
 
 ## Contributing
 

data/Rakefile

@@ -6,3 +6,6 @@ RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
 
+task :console do
+  sh 'pry -r ./lib/amorail.rb'
+end

data/lib/amorail/client.rb

@@ -71,7 +71,7 @@ module Amorail
       when 403
         fail ::Amorail::AmoForbiddenError
       when 404
-        fail ::Amorail::AmoNotFoudError
+        fail ::Amorail::AmoNotFoundError
       when 500
         fail ::Amorail::AmoInternalError
       when 502

data/lib/amorail/entity.rb

@@ -12,6 +12,11 @@ module Amorail
     class << self
       attr_reader :amo_name, :amo_response_name
 
+      # copy Amo names
+      def inherited(subclass)
+        subclass.amo_names amo_name, amo_response_name
+      end
+
       def amo_names(name, response_name = nil)
         @amo_name = @amo_response_name = name
         @amo_response_name = response_name unless response_name.nil?
@@ -34,17 +39,20 @@ module Amorail
       end
 
       def properties
-        @properties ||= {}
+        @properties ||=
+          superclass.respond_to?(:properties) ? superclass.properties.dup : {}
       end
-    end
 
-    amo_names 'entity'
+      def remote_url(action)
+        File.join(Amorail.config.api_path, amo_name, action)
+      end
+    end
 
     amo_field :id, :request_id, :responsible_user_id,
               date_create: :timestamp, last_modified: :timestamp
 
     delegate :client, :properties, to: Amorail
-    delegate :amo_name, to: :class
+    delegate :amo_name, :remote_url, to: :class
 
     def initialize(attributes = {})
       super(attributes)
@@ -75,16 +83,14 @@ module Amorail
     def merge_custom_fields(fields)
       return if fields.nil?
       fields.each do |f|
-        fname = "#{f.fetch('code').downcase}="
+        fname = f['code'] || f['name']
+        next if fname.nil?
+        fname = "#{fname.downcase}="
         fval = f.fetch('values').first.fetch('value')
         send(fname, fval) if respond_to?(fname)
       end
     end
 
-    def remote_url(action)
-      File.join(Amorail.config.api_path, self.class.amo_name, action)
-    end
-
     # call safe method <safe_request>. safe_request call authorize
     # if current session undefined or expires.
     def push(method)

data/lib/amorail/entity/finders.rb

@@ -1,15 +1,32 @@
 module Amorail # :nodoc: all
   class Entity
     class << self
+      # Find AMO entity by id
       def find(id)
         new.load_record(id)
       end
 
+      # Find AMO entity by id
+      # and raise RecordNotFound if nothing was found
       def find!(id)
         rec = find(id)
         fail RecordNotFound unless rec
         rec
       end
+
+      # Find AMO entities by query
+      # Returns array of matching entities.
+      def find_by_query(q)
+        response = Amorail.client.safe_request(
+          :get,
+          remote_url('list'),
+          query: q
+        )
+        return [] unless response.status == 200
+
+        (response.body['response'][amo_response_name] || [])
+          .map { |info| new.reload_model(info) }
+      end
     end
 
     def load_record(id)

data/lib/amorail/exceptions.rb

@@ -13,7 +13,7 @@ module Amorail
 
   class AmoForbiddenError < APIError; end
 
-  class AmoNotFoudError < APIError; end
+  class AmoNotFoundError < APIError; end
 
   class AmoInternalError < APIError; end
 

data/lib/amorail/property.rb

@@ -19,8 +19,10 @@ module Amorail
 
         def parse(data)
           hash = {}
-          data['custom_fields'][source_name].each do |contact|
-            hash[contact['code'].downcase] = PropertyItem.new(contact)
+          data['custom_fields'].fetch(source_name, []).each do |contact|
+            identifier = contact['code'].presence || contact['name'].presence
+            next if identifier.nil?
+            hash[identifier.downcase] = PropertyItem.new(contact)
           end
           new hash
         end
@@ -87,23 +89,33 @@ module Amorail
       self.source_name = 'companies'
     end
 
-    class Lead < StatusItem
-      def self.parse(data)
-        hash = {}
-        data['leads_statuses'].each do |prop|
-          hash[prop['name']] = PropertyItem.new(prop)
+    class Lead < PropertyItem
+      self.source_name = 'leads'
+
+      attr_accessor :statuses
+
+      class << self
+        def parse(data)
+          obj = super
+          hash = {}
+          data.fetch('leads_statuses', []).each do |prop|
+            hash[prop['name']] = PropertyItem.new(prop)
+          end
+          obj.statuses = hash
+          obj
         end
-        new hash
       end
     end
 
     class Task < PropertyItem
       def self.parse(data)
         hash = {}
-        data['task_types'].each do |tt|
+        data.fetch('task_types', []).each do |tt|
           prop_item = PropertyItem.new(tt)
-          hash[tt['code'].downcase] = prop_item
-          hash[tt['code']] = prop_item
+          identifier = tt['code'].presence || tt['name'].presence
+          next if identifier.nil?
+          hash[identifier.downcase] = prop_item
+          hash[identifier] = prop_item
         end
         new hash
       end

data/lib/amorail/version.rb

@@ -1,4 +1,4 @@
 # Amorail version
 module Amorail
-  VERSION = "0.1.6"
+  VERSION = "0.1.8"
 end

data/spec/contact_spec.rb

@@ -91,6 +91,28 @@ describe Amorail::Contact do
     end
   end
 
+  describe ".find_by_query" do
+    before { contacts_find_query_stub(Amorail.config.api_endpoint, 'foo') }
+    before { contacts_find_query_stub(Amorail.config.api_endpoint, 'faa', nil) }
+
+    it "loads entities" do
+      res = described_class.find_by_query('foo')
+      expect(res.size).to eq 2
+      expect(res.first.id).to eq 101
+      expect(res.last.id).to eq 102
+      expect(res.first.company_name).to eq "Foo Inc."
+      expect(res.last.email).to eq "foo2@tb.com"
+      expect(res.first.phone).to eq "1111 111 111"
+      expect(res.first.params[:id]).to eq 101
+    end
+
+    it "returns empty array" do
+      res = described_class.find_by_query('faa')
+      expect(res).to be_a(Array)
+      expect(res).to be_empty
+    end
+  end
+
   describe "#save" do
     before { contact_create_stub(Amorail.config.api_endpoint) }
 
@@ -114,13 +136,14 @@ describe Amorail::Contact do
 
     it "raise error if id is blank?" do
       obj = described_class.new
-      expect { obj.update!(name: 'Igor') }.to raise_error
+      expect { obj.update!(name: 'Igor') }
+        .to raise_error(Amorail::Entity::NotPersisted)
     end
 
     it "raise error" do
       obj = described_class.new
       expect { obj.update!(id: 101, name: "Igor") }
-        .to(raise_error)
+        .to(raise_error(Amorail::Entity::NotPersisted))
     end
   end
 end

data/spec/entity_spec.rb

@@ -1,6 +1,6 @@
 require "spec_helper"
 
-describe Amorail::Entity do
+describe MyEntity do
   before { mock_api }
 
   let(:entity) { described_class.new }

data/spec/fixtures/account_response.json

@@ -139,8 +139,30 @@
               "3392112": "MSN",
               "3392114": "OTHER"
             }
+          },
+          {
+            "id":  "116302",
+            "name":  "teachbase_id",
+            "multiple":  "N",
+            "type_id": "8"
           }
         ],
+        "leads": [
+          {
+            "id": "484604",
+            "name": "textfield",
+            "code": null,
+            "multiple": "N",
+            "type_id": "1"
+          },
+          {
+            "id": "484606",
+            "name": "Flag",
+            "code": null,
+            "multiple": "N",
+            "type_id": "3"
+          }
+          ],
         "companies": [
           {
             "id": "1460589",

data/spec/fixtures/contact_find_query.json

@@ -0,0 +1,59 @@
+{
+  "response": {
+    "contacts": [
+      {
+        "id": 101,
+        "name": "Foo bar",
+        "account_id": "8195968",
+        "last_modified": 1423139130,
+        "company_name": "Foo Inc.",
+        "custom_fields": 
+        [
+          {
+            "id": "1460591",
+            "name": "Email",
+            "code": "EMAIL",
+            "values": [
+              {
+                "value": "foo@tb.com",
+                "enum": "3392098"
+              }
+            ]
+          },
+          {
+            "id": "1460589",
+            "name": "Телефон",
+            "code": "PHONE",
+            "values": [
+              {
+                "value": "1111 111 111",
+                "enum": "3392086"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "id": 102,
+        "name": "Foo bar 2",
+        "account_id": "8195968",
+        "last_modified": 1423139150,
+        "company_name": "Foo Inc.",
+        "custom_fields": 
+        [
+          {
+            "id": "1460591",
+            "name": "Email",
+            "code": "EMAIL",
+            "values": [
+              {
+                "value": "foo2@tb.com",
+                "enum": "3392098"
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}

data/spec/fixtures/my_contact_find.json

@@ -0,0 +1,48 @@
+{
+  "response": {
+    "contacts": [
+      {
+        "id": 11,
+        "name": "Foo bar",
+        "account_id": "8195968",
+        "last_modified": 1423139130,
+        "company_name": "Foo Inc.",
+        "custom_fields": 
+        [
+          {
+            "id": "1460591",
+            "name": "Email",
+            "code": "EMAIL",
+            "values": [
+              {
+                "value": "foo@tb.com",
+                "enum": "3392098"
+              }
+            ]
+          },
+          {
+            "id": "1460589",
+            "name": "Телефон",
+            "code": "PHONE",
+            "values": [
+              {
+                "value": "1111 111 111",
+                "enum": "3392086"
+              }
+            ]
+          },
+          {
+            "id": "116302",
+            "name": "teachbase_id",
+            "values": [
+              {
+                "value": 1123,
+                "enum": "3392090"
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}

data/spec/helpers/webmock_helpers.rb

@@ -1,3 +1,4 @@
+# rubocop: disable Metrics/ModuleLength
 module AmoWebMock
   def mock_api
     authorize_stub(
@@ -85,6 +86,42 @@ module AmoWebMock
     end
   end
 
+  def my_contact_find_stub(endpoint, id, success = true)
+    if success
+      stub_request(
+        :get,
+        "#{endpoint}/private/api/v2/json/contacts/list?id=#{id}")
+        .to_return(
+          body: File.read('./spec/fixtures/my_contact_find.json'),
+          headers: { 'Content-Type' => 'application/json' },
+          status: 200
+        )
+    else
+      stub_request(
+        :get,
+        "#{endpoint}/private/api/v2/json/contacts/list?id=#{id}")
+        .to_return(body: nil, status: 204)
+    end
+  end
+
+  def contacts_find_query_stub(endpoint, query, success = true)
+    if success
+      stub_request(
+        :get,
+        "#{endpoint}/private/api/v2/json/contacts/list?query=#{query}")
+        .to_return(
+          body: File.read('./spec/fixtures/contact_find_query.json'),
+          headers: { 'Content-Type' => 'application/json' },
+          status: 200
+        )
+    else
+      stub_request(
+        :get,
+        "#{endpoint}/private/api/v2/json/contacts/list?query=#{query}")
+        .to_return(status: 204)
+    end
+  end
+
   def company_create_stub(endpoint)
     stub_request(:post, endpoint + '/private/api/v2/json/company/set')
       .to_return(

data/spec/my_contact_spec.rb

@@ -0,0 +1,48 @@
+require "spec_helper"
+
+describe MyContact do
+  before { mock_api }
+
+  describe ".properties" do
+    subject { described_class.properties }
+
+    specify do
+      is_expected.to include(:email, :phone, :teachbase_id)
+    end
+  end
+
+  describe "#params" do
+    let(:company) do
+      described_class.new(
+        name: 'Test inc',
+        phone: '12345678',
+        email: 'test@mala.ru',
+        teachbase_id: 123
+      )
+    end
+
+    subject { company.params }
+
+    specify { is_expected.to include(:last_modified) }
+    specify { is_expected.to include(name: 'Test inc') }
+
+    it "contains custom property" do
+      prop = subject[:custom_fields].detect { |p| p[:id] == "116302" }
+      expect(prop).not_to be_nil
+      expect(prop[:values].first[:value]).to eq 123
+    end
+  end
+
+  describe ".find" do
+    before { my_contact_find_stub(Amorail.config.api_endpoint, 11) }
+
+    it "loads entity" do
+      obj = described_class.find(11)
+      expect(obj.id).to eq 11
+      expect(obj.company_name).to eq "Foo Inc."
+      expect(obj.email).to eq "foo@tb.com"
+      expect(obj.teachbase_id).to eq 1123
+      expect(obj.params[:id]).to eq 11
+    end
+  end
+end

data/spec/property_spec.rb

@@ -28,9 +28,12 @@ describe Amorail::Property do
     expect(prop.contacts.position.id).to eq "1460587"
     expect(prop.contacts.phone.id).to eq "1460589"
     expect(prop.contacts.email.id).to eq "1460591"
+    expect(prop.contacts.teachbase_id.id).to eq "116302"
   end
 
   it "should parse leads hash" do
+    expect(prop.leads.textfield.id).to eq "484604"
+    expect(prop.leads.flag.id).to eq "484606"
     expect(prop.leads.statuses["Первичный контакт"].id).to eq "8195972"
     expect(prop.leads.statuses["Успешно реализовано"].id).to eq "142"
   end

data/spec/spec_helper.rb

@@ -8,7 +8,8 @@ require 'webmock/rspec'
 require 'shoulda/matchers'
 require 'helpers/webmock_helpers'
 
-ENV.clear
+# Cleanup Amorail env
+ENV.delete_if { |k, _| k =~ /amorail/i }
 ENV["AMORAIL_CONF"] = File.expand_path("../fixtures/amorail_test.yml", __FILE__)
 
 Dir[File.expand_path("../support/**/*.rb", __FILE__)].each { |f| require f }

data/spec/support/my_contact.rb

@@ -0,0 +1,3 @@
+class MyContact < Amorail::Contact # :nodoc:
+  amo_property :teachbase_id
+end

data/spec/support/my_entity.rb

@@ -0,0 +1,4 @@
+# We only need this class to set Amo names for core Entity
+class MyEntity < Amorail::Entity # :nodoc:
+  amo_names 'entity'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amorail
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - alekseenkoss
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-27 00:00:00.000000000 Z
+date: 2015-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -213,13 +213,18 @@ files:
 - spec/fixtures/amorail_test.yml
 - spec/fixtures/contact_create.json
 - spec/fixtures/contact_find.json
+- spec/fixtures/contact_find_query.json
 - spec/fixtures/contact_update.json
+- spec/fixtures/my_contact_find.json
 - spec/helpers/webmock_helpers.rb
 - spec/lead_spec.rb
+- spec/my_contact_spec.rb
 - spec/property_spec.rb
 - spec/spec_helper.rb
 - spec/support/entity_class_example.rb
 - spec/support/leadable_example.rb
+- spec/support/my_contact.rb
+- spec/support/my_entity.rb
 - spec/task_spec.rb
 homepage: ''
 licenses:
@@ -254,12 +259,17 @@ test_files:
 - spec/fixtures/amorail_test.yml
 - spec/fixtures/contact_create.json
 - spec/fixtures/contact_find.json
+- spec/fixtures/contact_find_query.json
 - spec/fixtures/contact_update.json
+- spec/fixtures/my_contact_find.json
 - spec/helpers/webmock_helpers.rb
 - spec/lead_spec.rb
+- spec/my_contact_spec.rb
 - spec/property_spec.rb
 - spec/spec_helper.rb
 - spec/support/entity_class_example.rb
 - spec/support/leadable_example.rb
+- spec/support/my_contact.rb
+- spec/support/my_entity.rb
 - spec/task_spec.rb
 has_rdoc: