zoho_hub 0.1.25 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fb0e65b3b5261334de8e0132b49ba57069ac73795e0b8fbafd953525c321946
-  data.tar.gz: cffbddbec5d01c1128465494a536973ae4f0bd557e8d55581128bc51b89b8a5e
+  metadata.gz: bb0b0886637feb21a98d0a73f40cb3571a0ec2507dfd45b7eec9fd348b365276
+  data.tar.gz: 70638084911ec64dc02095d4cf085453ca13ba4ea28a3c983c79e235a1a5911e
 SHA512:
-  metadata.gz: 274a760138b2cc5f6799b07a30f8a68aaa0ed3fb9f0c118d53835ad10d8d31d1aae3298ec4a84d339a4bde4508643fd1d71ba7cfd4a583636c95784fef3268bd
-  data.tar.gz: 76422df68817cc51a1bc2e8bb2f95c5cdedf845ff2cfa322a7c6ddddd0d55d62cc8f18b4c820800d729de4320f3277e6dc65d3d2e1160e23c78fc14fcc8ac38d
+  metadata.gz: c5fc255597ced5c966a59b0db9de72ab6a67defca6c1a62e5e168f37bc70326f2c1cccd5cf3ab44369a94372277ca42c671965e50d742b315b26126882f1af72
+  data.tar.gz: 89fbe288d53b9ebf9c76f8229981deffcacc9d6fe484b6187f654430eb097c7e1b57719dafcc953cafbfafeec7f1d765c87794697b3d283b168cbd2c9f35ff03

data/.gitignore

@@ -7,8 +7,8 @@
 /pkg/
 /spec/reports/
 /tmp/
+/cache/*
 Gemfile.lock
-/cache/
 
 # 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.5.1
+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.rb

@@ -1,33 +1,34 @@
 # frozen_string_literal: true
 
-require 'active_support/core_ext/object/blank'
-require 'active_support/core_ext/string/inflections'
+require 'backports/2.3.0/hash' if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.3.0')
 
 require 'zoho_hub/version'
 require 'zoho_hub/auth'
 require 'zoho_hub/configuration'
 require 'zoho_hub/connection'
 require 'zoho_hub/errors'
-require 'zoho_hub/records/contact'
-require 'zoho_hub/records/potential'
-require 'zoho_hub/records/campaign'
-require 'zoho_hub/records/account'
-require 'zoho_hub/records/quote'
-require 'zoho_hub/records/vendor'
-require 'zoho_hub/records/product'
-require 'zoho_hub/records/attachment'
+require 'zoho_hub/base_record'
+require 'zoho_hub/settings/module'
+require 'zoho_hub/module_builder'
+
+require 'multi_json'
 
 module ZohoHub
   module_function
 
+  def root
+    File.expand_path(File.join(__dir__, '..'))
+  end
+
   def configuration
     @configuration ||= Configuration.new
   end
 
-  def connection
-    @connection
+  def configure
+    yield(configuration)
   end
 
+  # Callback for when the token is refreshed.
   def on_refresh(&block)
     @connection.on_refresh_cb = block
   end
@@ -35,24 +36,24 @@ module ZohoHub
   def setup_connection(params = {})
     raise "ERROR: #{params[:error]}" if params[:error]
 
-    connection_params = params.slice(:access_token, :expires_in, :api_domain, :refresh_token)
+    connection_params = params.dup.slice(:access_token, :expires_in, :api_domain, :refresh_token)
 
     @connection = Connection.new(connection_params)
   end
 
+  def connection
+    @connection
+  end
+
   def refresh_token?
-    return false unless connection.present?
+    return false unless connection
 
     connection.refresh_token?
   end
 
   def access_token?
-    return false unless connection.present?
+    return false unless connection
 
     connection.access_token?
   end
-
-  def configure
-    yield(configuration)
-  end
 end

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