vtiger-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7fc43fdf6a0d5af0bff7a7c986152c32be237eff204925eca7afee5964f2e053
+  data.tar.gz: d1a2942949716e03e712701982c1135ac0deb6b9968cde6e9f9a2f9d189ff72a
+SHA512:
+  metadata.gz: c88c64e9234f5705cbf153f60254793522cf3523617df8e42d4e30dba71f8dd01f327b7cf8e066efb033c3740cb4306c6e23715109251aa26ea31922a69cef1d
+  data.tar.gz: 1e4fb05bf0ed48ff2d580b35845cac1c812d66202b04566a82c6a6a7487540c9df9ccc044bebf886ba9430839b3797afc1dd759080db0abdb4286f2ef58f971a

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'pry-byebug'
+  gem 'rake', '~> 12.0'
+  gem 'rubocop', '~> 0.90'
+  gem 'webmock', '~> 3.9', '>= 3.9.1'
+end

data/Gemfile.lock

@@ -0,0 +1,81 @@
+PATH
+  remote: .
+  specs:
+    vtiger-ruby (0.1.0)
+      faraday (~> 1.0.1)
+      json (~> 2.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    ast (2.4.1)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    crack (0.4.4)
+    diff-lcs (1.4.4)
+    faraday (1.0.1)
+      multipart-post (>= 1.2, < 3)
+    hashdiff (1.0.1)
+    json (2.3.1)
+    method_source (1.0.0)
+    multipart-post (2.1.1)
+    parallel (1.19.2)
+    parser (2.7.1.4)
+      ast (~> 2.4.1)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.9.0)
+      byebug (~> 11.0)
+      pry (~> 0.13.0)
+    public_suffix (4.0.6)
+    rainbow (3.0.0)
+    rake (12.3.3)
+    regexp_parser (1.7.1)
+    rexml (3.2.4)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.2)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.3)
+    rubocop (0.90.0)
+      parallel (~> 1.10)
+      parser (>= 2.7.1.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.7)
+      rexml
+      rubocop-ast (>= 0.3.0, < 1.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (0.4.0)
+      parser (>= 2.7.1.4)
+    ruby-progressbar (1.10.1)
+    unicode-display_width (1.7.0)
+    webmock (3.9.1)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  pry-byebug
+  rake (~> 12.0)
+  rspec (~> 3.9)
+  rubocop (~> 0.90)
+  vtiger-ruby!
+  webmock (~> 3.9, >= 3.9.1)
+
+BUNDLED WITH
+   2.1.4

data/README.md

@@ -0,0 +1,102 @@
+# VtigerRuby
+
+VtigerRuby is a Ruby SDK for the Vtiger CRM API.
+
+Official documentation of the Vtiger API can be found here:
+
+1. [Vtiger REST API Docs](https://www.vtiger.com/docs/rest-api-for-vtiger)
+2. [Vtiger Third Party Integrations](https://community.vtiger.com/help/vtigercrm/developers/third-party-app-integration.html)
+
+## Getting Started
+
+* Retrieve your `Accesskey` token information from the `My Preferences` page in the CRM Web UI.
+* `username` information used when signing into your instance of the CRM.
+* `endpoint` url specific to your instance, eg: https://your_instance.odx.vtiger.com/restapi/v1/vtiger/default
+
+> Installation information coming soon...
+
+### Creating a Client
+
+```ruby
+require 'vtiger-ruby'
+```
+
+```ruby
+endpoint = ENV['VTIGER_ENDPOINT']
+username = ENV['VTIGER_USERNAME']
+accesskey = ENV['VTIGER_ACCESSS_KEY']
+```
+
+```ruby
+client = VtigerRuby::Client.new(
+  endpoint: endpoint,
+  username: username,
+  accesskey: accesskey
+)
+```
+
+### Authentication
+
+Vtiger API Authentication happens in two steps:
+
+1. Request the challenge token
+```ruby
+client.get_challenge
+```
+
+2. Login request
+```ruby
+client.login
+```
+
+Alternatively, you can authenticate the client using the `connect` method.
+This single method call negates the need to complete `step 1` & `step 2` listed above.
+```ruby
+  client.connect
+```
+
+## Models
+
+The SDK arranges default [Vtiger CRM Modules](https://www.vtiger.com/docs/rest-api-for-vtiger#/CRM_Modules) into `model` classes.
+The model class can then be used to perform operations against the corresponding Vtiger module.
+
+### Account
+
+```ruby
+client.account.all # Retrieves all Vtiger Account module records
+```
+
+You can also retrieve all Vtiger Account module records from the `VtigerRuby::Account` model.
+
+```ruby
+VtigerRuby::Account.class_config(client) # Configures the class with client model
+VtigerRuby::Account.all # Retrieves all Vtiger Account module records
+```
+
+## Example
+
+```ruby
+require 'vtiger-ruby'
+
+# Credential information specific to vtiger instance
+endpoint = ENV['VTIGER_ENDPOINT']
+username = ENV['VTIGER_USERNAME']
+accesskey = ENV['VTIGER_ACCESSS_KEY']
+
+# Initializes the VtigerRuby client
+client = VtigerRuby::Client.new(
+  endpoint: endpoint,
+  username: username,
+  accesskey: accesskey
+)
+
+# Requests Vtiger challenge token and login
+client.connect
+
+# Retrieves all account records from the Account module
+accounts = client.account.all
+```
+
+## Code Status
+
+[![Maintainability](https://api.codeclimate.com/v1/badges/25a5fa53236293d044d8/maintainability)](https://codeclimate.com/github/ymukmar/vtiger-ruby/maintainability) [![Build Status](https://travis-ci.com/ymukmar/vtiger-ruby.svg?branch=main)](https://travis-ci.com/ymukmar/vtiger-ruby)

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/vtiger-ruby.rb

@@ -0,0 +1,12 @@
+require 'vtiger-ruby/version'
+require 'vtiger-ruby/client'
+
+require 'vtiger-ruby/api/query'
+
+require 'vtiger-ruby/models/vtiger_model'
+require 'vtiger-ruby/models/account'
+
+module VtigerRuby
+  class << self
+  end
+end

data/lib/vtiger-ruby/api/query.rb

@@ -0,0 +1,53 @@
+module VtigerRuby
+  module Api
+    class Query
+      def initialize(client, sql_query: nil)
+        @sql_query = sql_query
+        @client = client
+      end
+
+      def fetch_all
+        result = []
+        latest_fetch = fetch
+
+        until latest_fetch.empty?
+          result.concat(latest_fetch)
+          latest_fetch = fetch
+        end
+        result
+      end
+
+      def fetch(sql_query = nil)
+        params = {
+          'operation': 'query',
+          'sessionName': @client.session_id,
+          'query': sql_query || sql_for_records_after(last_record_id)
+        }
+
+        @query_response = Faraday.get(@client.endpoint, params) do |req|
+          req.headers['User-Agent'] = 'VtigerRuby'
+        end
+
+        JSON.parse(@query_response.body).dig('result')
+      end
+
+      private
+      def sql_for_records_after(record_id)
+        <<-SQL
+        #{@sql_query.gsub(':record_filter_clause', "id > #{record_id};")}
+        SQL
+      end
+
+      def last_record_id
+        response = @query_response.dup
+
+        unless response.nil? || (response = JSON.parse(response.body).dig('result')).empty?
+          response.last.dig('id')
+        else
+          # returns first N records where N <= 200 records
+          'x0'
+        end
+      end
+    end
+  end
+end

data/lib/vtiger-ruby/client.rb

@@ -0,0 +1,80 @@
+require 'faraday'
+require 'json'
+
+module VtigerRuby
+  class Client
+    attr_accessor :endpoint, :username, :accesskey, :session_id
+
+    def initialize(endpoint: nil, username: nil, accesskey: nil)
+      @endpoint = endpoint
+      @username = username
+      @accesskey = accesskey
+    end
+
+    def get_challenge
+      challenge_params = { operation: 'getchallenge', username: username }
+
+      response = Faraday.get(endpoint, challenge_params) do |req|
+        req.headers['User-Agent'] = 'VtigerRuby'
+      end
+
+      body = JSON.parse(response.body)
+      @token = body['result']['token']
+
+      body
+    end
+
+    def login
+      login_params = {
+        'operation': 'login',
+        'username': username,
+        'accessKey': md5_token
+      }
+
+      response = Faraday.post(endpoint) do |req|
+        req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+        req.headers['User-Agent'] = 'VtigerRuby'
+        req.body = login_params
+      end
+
+      body = JSON.parse(response.body)
+      @session_id = body['result']['sessionName']
+
+      body
+    end
+
+    def connect
+      get_challenge
+      login
+    end
+
+    def logout
+      logout_params = {
+        'operation': 'logout',
+        'sessionName': @session_id
+      }
+
+      response = Faraday.post(endpoint) do |req|
+        req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+        req.headers['User-Agent'] = 'VtigerRuby'
+        req.body = logout_params
+      end
+
+      remove_instance_variable(:@token)
+      remove_instance_variable(:@session_id)
+      remove_instance_variable(:@md5_token)
+
+      JSON.parse(response.body)
+    end
+
+    def account
+      VtigerRuby::Account.class_config(self)
+      VtigerRuby::Account
+    end
+
+    private
+    def md5_token
+      @md5_token ||= Digest::MD5.hexdigest(@token + accesskey)
+    end
+  end
+end

data/lib/vtiger-ruby/models/account.rb

@@ -0,0 +1,13 @@
+module VtigerRuby
+  class Account < VtigerModel
+    VTIGER_MODULE = 'Accounts'.freeze
+
+    def self.all
+      all_from_vtiger(self, 'select * from Accounts where :record_filter_clause')
+    end
+
+    def self.fetch(sql_query = nil)
+      fetch_from_vtiger(self, sql_query)
+    end
+  end
+end

data/lib/vtiger-ruby/models/vtiger_model.rb

@@ -0,0 +1,36 @@
+module VtigerRuby
+  class VtigerModel
+    def self.class_config(client)
+      @@client = client
+    end
+
+    def self.all_from_vtiger(klass, sql_query)
+      VtigerRuby::Api::Query
+        .new(@@client, sql_query: sql_query)
+          .fetch_all
+            .reduce([]) do |memo, data|
+              memo << klass.new(@@client, data)
+            end
+    end
+
+    def self.fetch_from_vtiger(klass, sql_query)
+      VtigerRuby::Api::Query
+        .new(@@client)
+          .fetch(sql_query)
+            .reduce([]) do |memo, data|
+              memo << klass.new(@@client, data)
+            end
+    end
+
+    def initialize(client, attribs = {})
+      @client = client
+      self.attributes = attribs unless attribs.empty?
+    end
+
+    attr_accessor :fetch_response
+
+    def attributes=(hash)
+      @fetch_response = hash
+    end
+  end
+end

data/lib/vtiger-ruby/version.rb

@@ -0,0 +1,3 @@
+module VtigerRuby
+  VERSION = '0.1.0'
+end

data/spec/quality_spec.rb

@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe VtigerRuby do
+  it 'returns the current version number' do
+    expect(VtigerRuby::VERSION).to eq('0.1.0')
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,42 @@
+require 'vtiger-ruby'
+require 'webmock/rspec'
+
+VTIGER_API_RESPONSE = {
+  challenge: {
+    "success": true,
+    "result": {
+        "token": 'test_token',
+        "serverTime": 1599816377,
+        "expireTime": 1599816677
+    }
+  },
+  login: {
+    "success": true,
+    "result": {
+        "sessionName": 'test_session_id',
+        "userId": '19x101',
+        "version": '0.22',
+        "vtigerVersion": '7.20.9.1'
+    }
+  }
+}
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |c|
+    c.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.before(:each) do
+    stub_request(:get, /your_instance.odx.vtiger.com/).
+      to_return(status: 200, body: VTIGER_API_RESPONSE[:challenge].to_json)
+
+    stub_request(:post, /your_instance.odx.vtiger.com/).
+      to_return(status: 200, body: VTIGER_API_RESPONSE[:login].to_json)
+  end
+end
+
+WebMock.disable_net_connect!(allow_localhost: true)

data/spec/vtiger-ruby/client_spec.rb

@@ -0,0 +1,92 @@
+require 'spec_helper'
+
+describe VtigerRuby::Client do
+  let(:endpoint) { 'https://your_instance.odx.vtiger.com/webservice.php?' }
+  let(:username) { 'test@example.com' }
+  let(:accesskey) { 'testAccessKey' }
+  let(:client) { described_class.new(endpoint: endpoint, username: username, accesskey: accesskey) }
+
+  describe 'get_challenge' do
+    it 'sets @token' do
+      expected = VTIGER_API_RESPONSE[:challenge][:result][:token]
+
+      client.get_challenge
+
+      expect(client.instance_variable_get(:@token)).to eq(expected)
+    end
+  end
+
+  describe 'login' do
+    it 'sets @session_id and @md5_token' do
+      token = VTIGER_API_RESPONSE[:challenge][:result][:token]
+      expected = VTIGER_API_RESPONSE[:login][:result][:sessionName]
+      md5_token = Digest::MD5.hexdigest(token + accesskey)
+
+      client.instance_variable_set(:@token, token)
+      client.login
+
+      expect(client.instance_variable_get(:@session_id)).to eq(expected)
+      expect(client.instance_variable_get(:@md5_token)).to eq(md5_token)
+    end
+  end
+
+  describe 'connect' do
+    it 'sets @token, @md5_token and @session_id' do
+      token = VTIGER_API_RESPONSE[:challenge][:result][:token]
+      session_id = VTIGER_API_RESPONSE[:login][:result][:sessionName]
+      md5_token = Digest::MD5.hexdigest(token + accesskey)
+
+      client.connect
+
+      expect(client.instance_variable_get(:@session_id)).to eq(session_id)
+      expect(client.instance_variable_get(:@token)).to eq(token)
+      expect(client.instance_variable_get(:@md5_token)).to eq(md5_token)
+    end
+  end
+
+  describe 'logout' do
+    it 'unsets @token' do
+      token = VTIGER_API_RESPONSE[:challenge][:result][:token]
+
+      client.connect
+
+      expect { client.logout }
+        .to change { client.instance_variable_get(:@token) }
+          .from(token)
+            .to(nil)
+    end
+
+    it 'unsets @session_id' do
+      session_id = VTIGER_API_RESPONSE[:login][:result][:sessionName]
+
+      client.connect
+
+      expect { client.logout }
+        .to change { client.instance_variable_get(:@session_id) }
+          .from(session_id)
+            .to(nil)
+    end
+
+    it 'unsets @md5_token' do
+      token = VTIGER_API_RESPONSE[:challenge][:result][:token]
+      md5_token = Digest::MD5.hexdigest(token + accesskey)
+
+      client.connect
+
+      expect { client.logout }
+        .to change { client.instance_variable_get(:@md5_token) }
+          .from(md5_token)
+            .to(nil)
+    end
+  end
+
+  describe 'account' do
+    it 'sets the client as a class object and returns the account class' do
+      client.connect
+
+      expect(client.account.class_variable_get(:@@client)).to eq(client)
+      expect(client.account.class_variable_get(:@@client)).to be_a(VtigerRuby::Client)
+      expect(client.account).to eq(VtigerRuby::Account)
+    end
+  end
+end

data/vtiger-ruby.gemspec

@@ -0,0 +1,21 @@
+require_relative 'lib/vtiger-ruby/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'vtiger-ruby'
+  spec.version       = VtigerRuby::VERSION
+  spec.authors       = ["Yedidia Muk'mar"]
+  spec.summary       = 'Vtiger API Ruby SDK'
+  spec.description   = 'Vtiger API Library for Ruby applications'
+  spec.homepage      = 'https://github.com/ymukmar/vtiger-ruby'
+
+  spec.required_ruby_version = '>= 2.5.1'
+
+  spec.add_runtime_dependency 'faraday', '~> 1.0.1'
+  spec.add_runtime_dependency 'json', '~> 2.3'
+  spec.add_development_dependency 'rspec', '~> 3.9'
+  spec.add_development_dependency 'webmock', '~> 3.9'
+
+  spec.files = `find *`.split("\n").uniq.sort
+  spec.executables   = []
+  spec.require_paths = ['lib']
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: vtiger-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yedidia Muk'mar
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-10-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+description: Vtiger API Library for Ruby applications
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- lib/vtiger-ruby.rb
+- lib/vtiger-ruby/api/query.rb
+- lib/vtiger-ruby/client.rb
+- lib/vtiger-ruby/models/account.rb
+- lib/vtiger-ruby/models/vtiger_model.rb
+- lib/vtiger-ruby/version.rb
+- spec/quality_spec.rb
+- spec/spec_helper.rb
+- spec/vtiger-ruby/client_spec.rb
+- spec/vtiger-ruby/models/account_spec.rb
+- spec/vtiger-ruby/models/vtiger_model_spec.rb
+- vtiger-ruby.gemspec
+homepage: https://github.com/ymukmar/vtiger-ruby
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: Vtiger API Ruby SDK
+test_files: []