zoho_hub 0.1.29 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c0b66c76f28dcdef377d2aa2b8747ba5dc5b78864278bf7e2c33067233abb49
-  data.tar.gz: 6521445a8b48fea2334bbb0e58e722cbed45576ffbd2515a26d2ac3e7bfc7c84
+  metadata.gz: bb0b0886637feb21a98d0a73f40cb3571a0ec2507dfd45b7eec9fd348b365276
+  data.tar.gz: 70638084911ec64dc02095d4cf085453ca13ba4ea28a3c983c79e235a1a5911e
 SHA512:
-  metadata.gz: d9840d0c83c4f18591eababff051b1e42f1dbdfffb5641ac2e075bade45736d7af6d3f43f6153ca3fbf4033ee4a2fdfb180d81a6675e112520250355da881fa0
-  data.tar.gz: 57ca1b772ed065f8d3f7377ba3be41905616ad4c812b9e6cc5dc6b57ae3a90aad6bfec417e6b24d373ec1b0e6e099258ad9187cb8ce731cb4e065a2cb8d44dc3
+  metadata.gz: c5fc255597ced5c966a59b0db9de72ab6a67defca6c1a62e5e168f37bc70326f2c1cccd5cf3ab44369a94372277ca42c671965e50d742b315b26126882f1af72
+  data.tar.gz: 89fbe288d53b9ebf9c76f8229981deffcacc9d6fe484b6187f654430eb097c7e1b57719dafcc953cafbfafeec7f1d765c87794697b3d283b168cbd2c9f35ff03

data/.gitignore

@@ -7,9 +7,8 @@
 /pkg/
 /spec/reports/
 /tmp/
+/cache/*
 Gemfile.lock
-/cache/
-.DS_Store
 
 # rspec failure tracking
 .rspec_status

data/.rspec

@@ -1,3 +1,4 @@
 --format documentation
 --color
 --require spec_helper
+--order rand

data/.rubocop.yml

@@ -7,6 +7,10 @@ AllCops:
 Style/Documentation:
   Enabled: false
 
+# Safe navigation is not available in older ruby versions
+Style/SafeNavigation:
+  Enabled: false
+
 # A good line length is 100 chars
 Metrics/LineLength:
   Max: 100

data/.ruby-version

@@ -1 +1 @@
-2.7.2
+2.5.3

data/.travis.yml

@@ -1,5 +1,8 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.5.0
-before_install: gem install bundler -v 2.0.1
+  - 2.1.10
+  - 2.2.10
+  - 2.3.7
+  - 2.4.4
+  - 2.5.3

data/README.md

@@ -1,6 +1,16 @@
 # ZohoHub
 
-https://www.zoho.com/crm/help/api-diff/
+[![Build Status](https://travis-ci.com/rikas/zoho_hub.svg?branch=master)](https://travis-ci.com/rikas/zoho_hub)
+[![Gem Version](https://badge.fury.io/rb/zoho_hub.svg)](https://badge.fury.io/rb/zoho_hub)
+
+Simple wrapper around Zoho CRM version2, using [OAuth 2.0 protocol](https://www.zoho.com/crm/help/api/v2/#OAuth2_0)
+for authentication.
+
+This gem reads your Module configuration and builds the corresponding classes for you, using some
+reflection mechanisms. You should then be able to use simple classes with an API close to
+ActiveRecord, to do CRUD operations.
+
+**NOTE: this gem is WIP, please try to use it and open an issue if you run into limitations / problems**
 
 ## Installation
 
@@ -18,9 +28,86 @@ Or install it yourself as:
 
     $ gem install zoho_hub
 
-## Usage
+## Setup process
+
+### 1. Register your application
+
+If you want to access your Zoho CRM account from your application you first need to create your
+application as described here: https://www.zoho.com/crm/help/api/v2/#oauth-request.
+
+**TODO TODO - explain "Authorized redirect URIs"**
+
+This will give you a **Client ID** and a **secret**, that you'll use in the next step.
+
+### 2. Configure ZohoHub with your credentials
+
+You need to have a configuration block like the one below (in rails add a `zoho_hub.rb` in your
+`config/initializers` dir):
+
+```ruby
+ZohoHub.configure do |config|
+  config.client_id    = 'YOUR_ZOHO_CLIENT_ID' # obtained in 1.
+  config.secret       = 'YOUR_ZOHO_SECRET'    # obtained in 1.
+  config.redirect_uri = 'YOUR_ZOHO_OAUTH_REDIRECT_URL'
+  # config.debug      = true # this will be VERY verbose, but helps to identify bugs / problems
+end
+```
+
+**Note:** if you don't know what the `redirect_url` is then **TODO TODO TODO TODO TODO**
+
+### 2. Authorization request
+
+In order to access data in Zoho CRM you need to authorize ZohoHub to access your account. To do so
+you have to request a specific URL with the right **scope** and **access_type**.
+
+To get the right URL you can use this simple line of code:
+
+```ruby
+ZohoHub::Auth.auth_url
+# => "https://accounts.zoho.eu/oauth/v2/auth?access_type=offline&client_id=&redirect_uri=&response_type=code&scope=ZohoCRM.modules.custom.all,ZohoCRM.settings.all,ZohoCRM.modules.contacts.all,ZohoCRM.modules.all"
+```
+
+If you request this generated URL you should see a screen like this one, where you have to click on "Accept":
+
+![](https://duaw26jehqd4r.cloudfront.net/items/1h1i3C1N0k0i02092F0S/Screen%20Shot%202018-11-25%20at%2019.18.38.png)
+
+You can change the default scope (what data can be accessed by your application). This is the list
+provided as the default scope:
+
+```
+ZohoCRM.modules.custom.all
+ZohoCRM.settings.all
+ZohoCRM.modules.contacts.all
+ZohoCRM.modules.all
+```
+
+To get the URL for a different scope you can provide a `scope` argument:
+
+```ruby
+ZohoHub::Auth.auth_url(scope: ['ZohoCRM.modules.custom.all', 'ZohoCRM.modules.all'])
+# => "https://accounts.zoho.eu/oauth/v2/auth?access_type=offline&client_id=&redirect_uri=&response_type=code&scope=ZohoCRM.modules.custom.all,ZohoCRM.modules.all"
+```
+
+#### 2.1 Offline access
+
+By design the access tokens returned by the OAuth flow expire after a period of time (1 hour by
+default), as a safety mechanism. This means that any application that wants to work with a user's
+data needs the user to have recently gone through the OAuth flow, aka be online.
+
+When you request offline access the Zoho API returns a refresh token. Refresh tokens give your
+application the ability to request data on behalf of the user when the user is not present and in
+front of your application.
+
+**By default `ZohoHub::Auth.auth_url` will request offline access**
+
+You can force "online" access by using `#auth_url` with a `access_type` argument:
+
+```ruby
+ZohoHub::Auth.auth_url(access_type: 'online')
+# => "https://accounts.zoho.eu/oauth/v2/auth?access_type=online&client_id=&redirect_uri=&response_type=code&scope=ZohoCRM.modules.custom.all,ZohoCRM.settings.all,ZohoCRM.modules.contacts.all,ZohoCRM.modules.all"
+```
 
-TODO: Write usage instructions here
+## 3. Generate Access Token
 
 ## Development
 
@@ -28,10 +115,7 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 the tests. You can also run `bin/console` for an interactive prompt that will allow you to
 experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new
-version, update the version number in `version.rb`, and then run `bundle exec rake release`, which
-will create a git tag for the version, push git commits and tags, and push the `.gem` file
-to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 

data/bin/console

@@ -8,16 +8,15 @@ require 'dotenv'
 Dotenv.load
 
 ZohoHub.configure do |config|
-  config.client_id = ENV['ZOHO_CLIENT_ID']
-  config.secret = ENV['ZOHO_SECRET']
-  config.redirect_uri = ENV['ZOHO_OAUTH_REDIRECT_URL']
-  config.debug = true
+  config.client_id    = ENV['ZOHO_CLIENT_ID']
+  config.secret       = ENV['ZOHO_SECRET']
+  config.debug        = ENV['ZOHO_DEBUG'] || false
 end
 
+# We assume that we already have a refresh token, to make things easier here.
+puts 'Refreshing token...'
 token_params = ZohoHub::Auth.refresh_token(ENV['ZOHO_REFRESH_TOKEN'])
 ZohoHub.setup_connection(token_params)
 
-self.send(:include, ZohoHub)
-
 require 'pry'
 Pry.start

data/bin/read

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'zoho_hub'
+require 'zoho_hub/settings/module'
+require 'zoho_hub/records/base_record'
+
+require 'dotenv'
+Dotenv.load
+
+ZohoHub.configure do |config|
+  config.client_id    = ENV['ZOHO_CLIENT_ID']
+  config.secret       = ENV['ZOHO_SECRET']
+  config.redirect_uri = ENV['ZOHO_OAUTH_REDIRECT_URL']
+end
+
+token_params = ZohoHub::Auth.refresh_token(ENV['ZOHO_REFRESH_TOKEN'])
+ZohoHub.setup_connection(token_params)
+
+puts "Reading modules for client ID: #{ENV['ZOHO_CLIENT_ID']}..."
+
+modules_hashes = ZohoHub::Settings::Module.all_json
+
+puts "Found #{modules_hashes.size} modules"
+
+modules_hashes.each do |hash|
+  puts "- Writing configuration for #{hash[:plural_label]}"
+
+  file_name = File.join(ZohoHub.root, 'cache', 'modules', "#{hash[:api_name]}.json")
+
+  File.open(file_name, 'w') do |file|
+    file.write(JSON.pretty_generate(hash))
+  end
+
+  next unless hash[:api_supported]
+
+  fields_array = ZohoHub::Settings::Field.all_json_for(hash[:api_name])
+  file_name = File.join(ZohoHub.root, 'cache', 'fields', "#{hash[:api_name]}.json")
+
+  File.open(file_name, 'w') do |file|
+    file.write(JSON.pretty_generate(fields_array))
+  end
+end

data/bin/setup

@@ -4,5 +4,3 @@ IFS=$'\n\t'
 set -vx
 
 bundle install
-
-# Do any other automated setup that you need to do here

data/bin/zoho_hub

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+require 'zoho_hub'
+require 'zoho_hub/auth'
+require 'zoho_hub/oauth_callback_server'
+
+require 'launchy'
+require 'optparse'
+
+default_port = ZohoHub::OauthCallbackServer.settings.port
+
+options = {}
+parser = OptionParser.new do |op|
+  op.banner = 'Usage: zoho_hub -c CLIENT_ID -s SECRET [options]'
+
+  op.on('-c', '--client-id=client_id', 'The Zoho client ID') do |client|
+    options[:client_id] = client
+  end
+
+  op.on('-s', '--secret=secret', 'The Zoho secret') do |secret|
+    options[:secret] = secret
+  end
+
+  op.on('-p', '--port=port', "The port for your callback (default #{default_port})") do |port|
+    options[:port] = port
+  end
+
+  op.on_tail('--version', 'Show version') do
+    puts "ZohoHub #{ZohoHub::VERSION}"
+    exit
+  end
+end
+
+parser.parse!
+
+abort(parser.help) if options[:client_id].nil? || options[:secret].nil?
+
+callback_path = ZohoHub::OauthCallbackServer::CALLBACK_PATH
+
+ZohoHub::OauthCallbackServer.set(:port, options[:port]) if options[:port]
+
+bind_port = ZohoHub::OauthCallbackServer.settings.port
+bind_address = ZohoHub::OauthCallbackServer.settings.bind
+
+callback_url = "http://#{bind_address}:#{bind_port}/#{callback_path}"
+
+puts "Callback URL: #{callback_url}"
+
+ZohoHub.configure do |config|
+  config.client_id    = options[:client_id]
+  config.secret       = options[:secret]
+  config.redirect_uri = callback_url
+  config.debug        = true
+end
+
+# Open the URL in the browser
+url = ZohoHub::Auth.auth_url
+puts "REQUESTING: #{url}"
+Launchy.open(url)

data/lib/zoho_hub/auth.rb

@@ -6,11 +6,12 @@ require 'faraday_middleware'
 require 'addressable'
 
 module ZohoHub
+  # Class that takes care of authentication using Oauth2 workflow as described here:
+  # https://www.zoho.com/crm/help/api/v2/#oauth-request.
   class Auth
     extend Forwardable
 
     TOKEN_PATH = '/oauth/v2/token'
-    REVOKE_TOKEN_PATH = '/oauth/v2/token/revoke'
     AUTH_PATH = '/oauth/v2/auth'
 
     DEFAULT_SCOPES = %w[
@@ -22,22 +23,30 @@ module ZohoHub
 
     DEFAULT_ACCESS_TYPE = 'offline'
 
-    def_delegators :@configuration, :redirect_uri, :client_id, :secret
+    def_delegators :@configuration, :redirect_uri, :client_id, :secret, :api_domain
 
-    def initialize(access_type: nil, scopes: nil)
+    def initialize(access_type: DEFAULT_ACCESS_TYPE, scopes: DEFAULT_SCOPES)
       @configuration = ZohoHub.configuration
-      @access_type = access_type || ZohoHub.configuration.access_type
-      @scopes = scopes || DEFAULT_SCOPES
+      @access_type = access_type
+      @scopes = scopes
     end
 
-    def self.auth_url
-      new.auth_url
+    def token_full_uri
+      Addressable::URI.join(api_domain, TOKEN_PATH)
+    end
+
+    def auth_full_uri
+      Addressable::URI.join(api_domain, AUTH_PATH)
+    end
+
+    def self.auth_url(access_type: DEFAULT_ACCESS_TYPE, scopes: DEFAULT_SCOPES)
+      new(access_type: access_type, scopes: scopes).auth_url
     end
 
     def auth_url
       uri = auth_full_uri
 
-      query = {
+      uri.query_values = {
         client_id: client_id,
         scope: @scopes.join(','),
         access_type: @access_type,
@@ -45,27 +54,21 @@ module ZohoHub
         response_type: 'code'
       }
 
-      # The consent page must be presented otherwise we don't get the refresh token back.
-      query[:prompt] = 'consent' if @access_type == DEFAULT_ACCESS_TYPE
-
-      uri.query_values = query
-
       Addressable::URI.unencode(uri.to_s)
     end
 
-    def auth_full_uri
-      Addressable::URI.join(@configuration.base_url, AUTH_PATH)
-    end
-
-    def self.refresh_token(refresh_token)
-      new.refresh_token(refresh_token)
-    end
+    def token_url(grant_token)
+      uri = token_full_uri
 
-    def refresh_token(refresh_token)
-      result = Faraday.post(refresh_url(refresh_token))
+      uri.query_values = {
+        client_id: client_id,
+        client_secret: secret,
+        code: grant_token,
+        redirect_uri: redirect_uri,
+        grant_type: 'authorization_code'
+      }
 
-      json = parse(result.body)
-      json.merge(refresh_token: refresh_token)
+      Addressable::URI.unencode(uri.to_s)
     end
 
     def refresh_url(refresh_token)
@@ -81,16 +84,19 @@ module ZohoHub
       Addressable::URI.unencode(uri.to_s)
     end
 
-    def parse(body)
-      MultiJson.load(body, symbolize_keys: true)
+    def self.refresh_token(refresh_token)
+      new.refresh_token(refresh_token)
     end
 
-    def token_full_uri
-      Addressable::URI.join(@configuration.base_url, TOKEN_PATH)
+    def refresh_token(refresh_token)
+      result = Faraday.post(refresh_url(refresh_token))
+
+      json = parse(result.body)
+      json.merge(refresh_token: refresh_token)
     end
 
     def revoke_refresh_token(refresh_token)
-      uri = revoke_token_full_uri
+      uri = token_full_uri
 
       uri.query_values = { token: refresh_token }
 
@@ -101,10 +107,6 @@ module ZohoHub
       parse(result.body)
     end
 
-    def revoke_token_full_uri
-      Addressable::URI.join(@configuration.base_url, REVOKE_TOKEN_PATH)
-    end
-
     def self.get_token(grant_token)
       new.get_token(grant_token)
     end
@@ -115,20 +117,8 @@ module ZohoHub
       parse(result.body)
     end
 
-    def token_url(grant_token)
-      uri = token_full_uri
-
-      query = {
-        client_id: client_id,
-        client_secret: secret,
-        code: grant_token,
-        redirect_uri: redirect_uri,
-        grant_type: 'authorization_code'
-      }
-
-      uri.query_values = query
-
-      Addressable::URI.unencode(uri.to_s)
+    def parse(body)
+      MultiJson.load(body, symbolize_keys: true)
     end
   end
 end

data/lib/zoho_hub/base_record.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'zoho_hub/response'
+require 'zoho_hub/with_connection'
+require 'zoho_hub/with_attributes'
+require 'zoho_hub/string_utils'
+
+module ZohoHub
+  class BaseRecord
+    include WithConnection
+    include WithAttributes
+
+    # Default nnumber of records when fetching all.
+    DEFAULT_RECORDS_PER_PAGE = 200
+
+    # Default page number when fetching all.
+    DEFAULT_PAGE = 1
+
+    # Minimum number of records to fetch when fetching all.
+    MIN_RECORDS = 2
+
+    class << self
+      def request_path(name = nil)
+        @request_path = name if name
+        @request_path ||= StringUtils.pluralize(StringUtils.demodulize(to_s))
+        @request_path
+      end
+
+      def find(id)
+        body = get(File.join(request_path, id.to_s))
+        response = build_response(body)
+
+        if response.empty?
+          raise RecordNotFound, "Couldn't find #{request_path.singularize} with 'id'=#{id}"
+        end
+
+        new(response.data)
+      end
+
+      def where(params)
+        path = File.join(request_path, 'search')
+
+        response = get(path, params)
+        data = response[:data]
+
+        data.map { |info| new(info) }
+      end
+
+      def find_by(params)
+        records = where(params)
+        records.first
+      end
+
+      def create(params)
+        new(params).save
+      end
+
+      def all(options = {})
+        options[:page] ||= DEFAULT_PAGE
+        options[:per_page] ||= DEFAULT_RECORDS_PER_PAGE
+        options[:per_page] = MIN_RECORDS if options[:per_page] < MIN_RECORDS
+
+        body = get(request_path, options)
+        response = build_response(body)
+
+        data = response.nil? ? [] : response.data
+
+        data.map { |json| new(json) }
+      end
+
+      def exists?(id)
+        !find(id).nil?
+      rescue RecordNotFound
+        false
+      end
+
+      alias exist? exists?
+
+      def build_response(body)
+        response = Response.new(body)
+
+        raise InvalidTokenError, response.msg if response.invalid_token?
+        raise RecordInvalid, response.msg if response.invalid_data?
+
+        response
+      end
+    end
+
+    def save
+      body = if new_record? # create new record
+               post(self.class.request_path, data: [to_params])
+             else # update existing record
+               path = File.join(self.class.request_path, id)
+               put(path, data: [to_params])
+             end
+
+      response = build_response(body)
+
+      response.data.dig(:details, :id)
+    end
+
+    def new_record?
+      !id
+    end
+
+    def to_params
+      params = {}
+
+      attributes.each do |attr|
+        key = attr_to_zoho_key(attr)
+
+        params[key] = send(attr)
+      end
+
+      params
+    end
+
+    def build_response(body)
+      self.class.build_response(body)
+    end
+  end
+end

data/lib/zoho_hub/configuration.rb

@@ -2,17 +2,16 @@
 
 module ZohoHub
   class Configuration
-    attr_accessor :client_id, :secret, :redirect_uri, :base_url, :access_type
+    attr_accessor :client_id, :secret, :redirect_uri, :api_domain
     attr_writer :debug
 
-    DEFAULT_BASE_URL = 'https://accounts.zoho.eu'
+    DEFAULT_API_DOMAIN = 'https://accounts.zoho.eu'
 
     def initialize
       @client_id = ''
       @secret = ''
       @redirect_uri = ''
-      @base_url = DEFAULT_BASE_URL
-      @access_type = Auth::DEFAULT_ACCESS_TYPE
+      @api_domain = DEFAULT_API_DOMAIN
     end
 
     def debug?

data/lib/zoho_hub/connection.rb

@@ -22,43 +22,37 @@ module ZohoHub
     def initialize(access_token:, api_domain: DEFAULT_DOMAIN, expires_in: 3600, refresh_token: nil)
       @access_token = access_token
       @expires_in = expires_in
-      @api_domain = api_domain || DEFAULT_DOMAIN
+      @api_domain = api_domain
       @refresh_token ||= refresh_token # do not overwrite if it's already set
     end
 
-    def get(path, params = {}, &block)
+    def get(path, params = {})
       log "GET #{path} with #{params}"
 
-      response = with_refresh do
-        adapter(&block).get(path, params)
-      end
+      response = with_refresh { adapter.get(path, params) }
       response.body
     end
 
-    def post(path, params = {}, &block)
+    def post(path, params = {})
       log "POST #{path} with #{params}"
 
-      response = with_refresh do
-        adapter(&block).post(path, params)
-      end
+      response = with_refresh { adapter.post(path, params) }
       response.body
     end
 
-    def put(path, params = {}, &block)
+    def put(path, params = {})
       log "PUT #{path} with #{params}"
 
-      response = with_refresh do
-        adapter(&block).put(path, params)
-      end
+      response = with_refresh { adapter.put(path, params) }
       response.body
     end
 
     def access_token?
-      @access_token.present?
+      @access_token
     end
 
     def refresh_token?
-      @refresh_token.present?
+      @refresh_token
     end
 
     def log(text)
@@ -79,7 +73,7 @@ module ZohoHub
         log "Refreshing outdated token... #{@access_token}"
         params = ZohoHub::Auth.refresh_token(@refresh_token)
 
-        @on_refresh_cb.call(params) if @on_refresh_cb.present?
+        @on_refresh_cb.call(params) if @on_refresh_cb
 
         @access_token = params[:access_token]
 
@@ -104,7 +98,6 @@ module ZohoHub
       Faraday.new(url: base_url) do |conn|
         conn.headers = authorization_header if access_token?
         conn.use FaradayMiddleware::ParseJson
-        yield conn if block_given?
         conn.response :json, parser_options: { symbolize_names: true }
         conn.response :logger if ZohoHub.configuration.debug?
         conn.adapter Faraday.default_adapter