zoho_hub 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1967126d56677efb3373c3a3d8700842f5d03e0f3b0cb922b4ffcf5d113a831
-  data.tar.gz: 1cf0f3e67da7d878dd367614c3da7441d0024fe070dae978f72e49575e6be013
+  metadata.gz: 57cb4c2ca4e3b5f7f72773ae7b2492bd5335c7ff70b1ee014592b2f3f28eebe7
+  data.tar.gz: 64e3c1b8bf81edb48c6229d8e34b57f14ce9705bc4dbae8de32dddcccab54e2c
 SHA512:
-  metadata.gz: 203045fd8b960ae3dd03873106ea7a88a111bbd6618d9942e9c597cdef83ba860792639e13e92b7a32ad0d550b9521795ab8c4043dc8e9e2de44321a5e2a7990
-  data.tar.gz: ac2a1e1e7bca5a28196d9cdc68312c1a8774ddc1666266a0a4956587b482bf255da15aa50f9c05cb593a6768103f3b939a91ed692c16641cd26976ce51f63243
+  metadata.gz: c77c9a08e05a48efbb5e6472022d408a8e8c4902b34d04d95896408c2f17276ebc531bcf2969712c1528a8e93d0f0919e77f82df576bdc02a246419a753198e7
+  data.tar.gz: cd4d488c82598ec99a8c48b9823772b72041ebd2600965ffbbdec2b3a816776915cd72a28713c2c54cb1f7ec0b17db04955187e2f0a55bece5ed103aed06a19d

data/README.md

@@ -3,8 +3,8 @@
 [![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/developer/api/oauth-overview.html)
-for authentication.
+Simple wrapper around Zoho CRM version2, using
+[OAuth 2.0 protocol](https://www.zoho.com/crm/help/developer/api/oauth-overview.html) 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
@@ -12,6 +12,24 @@ 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**
 
+## Table of Contents
+
+* [Installation](#installation)
+* [Setup](#setup-process)
+  1. [Register your application](#1-register-your-application)
+  2. [Configure ZohoHub with your credentials](#2-configure-zohohub-with-your-credentials)
+  3. [Authorization request](#3-authorization-request)
+  4. [Access token](#4-access-token)
+  5. [Refresh token](#5-refresh-token)
+  6. [BasicZohoHub flow](#6-basic-zohohub-flow)
+  7. [BaseRecord and record classes](#7-baserecord-and-record-classes)
+* [Tips and suggestions](#tips-and-suggestions)
+* [Examples](#examples)
+  1. [Setup auth token and request CurrentUser](#setup-auth-token-and-request-currentuser)
+* [Development](#development)
+* [Contributing](#contributing)
+* [License](#license)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -35,19 +53,21 @@ Or install it yourself as:
 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/developer/api/register-client.html.
 
-This will give you a **Client ID** and a **secret**, that you'll use in step 2.
+This will give you a **Client ID** and a **secret**, that you'll use in
+[step 2](#2-configure-zohohub-with-your-credentials).
 
 #### 1.1 Zoho Accounts URL
 
 Registration and authorization requests are made to Zoho's domain-specific Accounts URL which
 varies depending on your region:
 
+* China: https://accounts.zoho.com.cn
 * EU: https://accounts.zoho.eu
+* India: https://accounts.zoho.in
 * US: https://accounts.zoho.com
-* China: https://accounts.zoho.com.cn
 
-ZohoHub uses the EU Account URL by default, but this can be overriden in a `ZohoHub.configure`
-block via the `api_domain` method (see step 2.)
+ZohoHub uses the EU Account URL by default, but this can be overriden in a `ZohoHub.configure` block
+via the `api_domain` method ([step 2](#2-configure-zohohub-with-your-credentials).)
 
 #### 1.2 Authorized Redirect URI
 
@@ -55,8 +75,11 @@ Per Zoho's API documentation, providing a **redirect URI** is optional. Doing so
 your application to be redirected back to your app (to the **redirect URI**) with a **grant token**
 upon successful authentication.
 
-If you don't provide a **redirect URI**, you'll need to use the [self-client option](https://www.zoho.com/crm/help/developer/api/auth-request.html#plink2)
-for authorization (see 3.2 below.)
+If you don't provide a **redirect URI**, you'll need to use the
+[self-client option](https://www.zoho.com/crm/help/developer/api/auth-request.html#self-client) for
+authorization (see [3.2](#32-self-client-authorization).)
+
+---
 
 ### 2. Configure ZohoHub with your credentials
 
@@ -65,7 +88,7 @@ for authorization (see 3.2 below.)
 > code directly by referencing them via environment variables. Use something like the dotenv gem or
 > encrypted credentials in Rails to keep them as secret and secure as possible.
 
-You need to have a configuration block like the one below (in rails add a `zoho_hub.rb` in your
+You need to have a configuration block like the one below (in Rails add a `zoho_hub.rb` in your
 `config/initializers` directory):
 
 ```ruby
@@ -78,6 +101,8 @@ ZohoHub.configure do |config|
 end
 ```
 
+---
+
 ### 3. Authorization request
 
 In order to access data in Zoho CRM you need to authorize ZohoHub to access your account. To do so
@@ -94,7 +119,8 @@ 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":
+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)
 
@@ -109,7 +135,8 @@ as follows (the value after `code=` is the **grant token**):
 
 If you don't have a **redirect URI** or you want your application to be able to authorize with Zoho
 programmatically (without a user required to be present and click the "Accept" prompt), Zoho
-provides a [self-client option](https://www.zoho.com/crm/help/developer/api/auth-request.html#plink2)
+provides a
+[self-client option](https://www.zoho.com/crm/help/developer/api/auth-request.html#self-client)
 for authentication which will provide a **grant token**.
 
 #### 3.3 More on scopes
@@ -131,7 +158,9 @@ ZohoHub::Auth.auth_url(scope: ['ZohoCRM.modules.custom.all', 'ZohoCRM.modules.al
 # => "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"
 ```
 
-Refer to [Zoho's API documentation on scopes](https://www.zoho.com/crm/help/developer/api/oauth-overview.html#plink5) for detailed information.
+Refer to
+[Zoho's API documentation on scopes](https://www.zoho.com/crm/help/developer/api/oauth-overview.html#scopes)
+for detailed information.
 
 #### 3.4 Offline access
 
@@ -139,9 +168,9 @@ By design the **access tokens** returned by the OAuth flow expire after a period
 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.
+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**
 
@@ -152,6 +181,8 @@ 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"
 ```
 
+---
+
 ### 4. Access token
 
 See Zoho's API documentation for generating an initial **access token**:
@@ -163,11 +194,14 @@ To use an **access token** in a manual request, include it as a request header a
 To use an **access token** with ZohoHub, pass it to the `ZohoHub.setup_connection` method as the
 `access_token` parameter.
 
+---
 
 ### 5. Refresh token
 
 TODO
 
+---
+
 ### 6. Basic ZohoHub flow
 
 Once ZohoHub has been configured with your credentials (section 2) and you have a fresh **access
@@ -186,7 +220,10 @@ Now you can issue requests to Zoho's API with the Connection object, e.g.:
 ZohoHub.connection.get 'Leads'
 ```
 
-A successful request will receive a response like the sample here: https://www.zoho.com/crm/help/developer/api/get-records.html.
+A successful request will receive a response like the sample here:
+https://www.zoho.com/crm/help/developer/api/get-records.html.
+
+---
 
 ### 7. BaseRecord and record classes
 
@@ -208,7 +245,7 @@ inherits from `ZohoHub::BaseRecord`. For example, to build a class for the Leads
 ```ruby
 # lead.rb
 
-class Lead < BaseRecord
+class Lead < ZohoHub::BaseRecord
   ...
 end
 ```
@@ -218,28 +255,34 @@ Specify this module's fields as attributes:
 ```ruby
 # lead.rb
 
-class Lead < BaseRecord
+class Lead < ZohoHub::BaseRecord
   attributes: :id, :first_name, :last_name, :phone, :email, :source, # etc.
 end
 ```
 
-Define an `initialize` method to populate attributes:
+Now you can issue requests more easily with your record class, e.g.:
 
 ```ruby
-def initialize(params)
-  attributes.each do |attr|
-    zoho_key = attr_to_zoho_key(attr)
+# Request a (paginated) list of all Lead records
+Lead.all
 
-    send("#{attr}=", params[zoho_key] || params[attr] || DEFAULTS[attr])
-  end
-end
+# Get the Lead instance with a specific ID
+Lead.find('78265000003433063')
 ```
 
-Now you can issue requests more easily with your record class, e.g.:
+And even create new Lead entries in Zoho:
 
 ```ruby
-# request a (paginated) list of all Lead records
-Lead.all
+lead = Lead.new(
+  first_name: 'First name',
+  last_name: 'Last name',
+  phone: '+35197736281',
+  email: 'myemail@gmail.com',
+  source: 'Homepage'
+)
+
+# Creates the new lead
+lead.save
 ```
 
 ## Tips and suggestions
@@ -252,10 +295,94 @@ Lead.all
   friend - especially the sample HTTP requests and responses in the various sections under "Rest
   API" on the left.
 * If you're manually implementing your record classes (rather than using the reflection mechanism),
-  the files in `/lib/zoho_hub/deprecated_and_only_for_reference_records/` can help you get started.
-* Requests can be issued to Zoho CRM's [Sandbox](https://help.zoho.com/portal/kb/articles/using-sandbox)
+  the files in `/examples/models/` can help you get started.
+* Requests can be issued to Zoho CRM's
+  [Sandbox](https://help.zoho.com/portal/kb/articles/using-sandbox)
   by configuring `https://crmsandbox.zoho.com/crm` (or regional equivalent) as the `api_domain`.
 
+## Examples
+
+### Setup auth token and request CurrentUser
+
+> This example assumes use of the dotenv gem and is written directly into
+> ZohoHub's root directory (rather than using ZohoHub as a gem) for simplicity.
+
+1. Edit `bin/console` to comment out refreshing the token and setting up the connection:
+
+```ruby
+# bin/console
+
+...
+# puts 'Refreshing token...'
+# token_params = ZohoHub::Auth.refresh_token(ENV['ZOHO_REFRESH_TOKEN'])
+# ZohoHub.setup_connection(token_params)
+...
+```
+
+2. [Register your application](#1-register-your-application) to obtain a **client ID** and
+**secret**. (Leave the [Zoho API Credentials page](https://accounts.zoho.com/developerconsole) open;
+you'll need it in step 5.)
+3. Determine your [Zoho Accounts URL](#11-zoho-accounts-url).
+4. Add your registration and account URL information to a `.env` file:
+
+```
+# .env
+
+ZOHO_CLIENT_ID=YOUR_CLIENT_ID
+ZOHO_SECRET=YOUR_SECRET
+ZOHO_API_DOMAIN=YOUR_ZOHO_ACCOUNTS_URL
+```
+
+5. On the [Zoho API Credentials page](https://accounts.zoho.com/developerconsole) from step 1, click
+the three vertical dots and select `Self client`.
+6. Paste this into the `Scope` field: `ZohoCRM.users.ALL`, choose an expiration time, and click
+`View Code`; this is your **Grant token**.
+7. Run the ZohoHub console from your terminal: `bin/console`
+8. Issue a token request with the **grant token** (notice the quotes around the token value):
+
+```ruby
+ZohoHub::Auth.get_token('paste_your_grant_token_here')
+```
+
+This should return a response with an **access token**, e.g.:
+
+```ruby
+=> {:access_token=>"ACCESS_TOKEN_VALUE",
+ :expires_in_sec=>3600,
+ :api_domain=>"https://www.zohoapis.com",
+ :token_type=>"Bearer"
+ }
+```
+
+exit the console with `exit`.
+
+9. Add the access token to your `.env` file:
+
+```
+# .env
+
+ZOHO_CLIENT_ID=YOUR_CLIENT_ID
+ZOHO_SECRET=YOUR_SECRET
+ZOHO_API_DOMAIN=YOUR_ZOHO_ACCOUNTS_URL
+ZOHO_ACCESS_TOKEN=YOUR_ACCESS_TOKEN
+```
+
+10. Edit `bin/console` to add a new `setup_connection` after the previously commented out one:
+
+```ruby
+# bin/console
+
+...
+# ZohoHub.setup_connection(token_params)
+
+ZohoHub.setup_connection(access_token: ENV['ZOHO_ACCESS_TOKEN'])
+...
+```
+
+11. Start the console again: `bin/console`.
+
+12. Issue a request for the current user: `ZohoHub.connection.get 'users?type=CurrentUser'`
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run
@@ -270,4 +397,5 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/rikas/
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/lib/zoho_hub/base_record.rb

@@ -42,6 +42,17 @@ module ZohoHub
       def where(params)
         path = File.join(request_path, 'search')
 
+        if params.size == 1
+          params = case params.keys.first
+                   when :criteria, :email, :phone, :word
+                     # these attributes are directly handled by Zoho
+                     # see https://www.zoho.com/crm/help/developer/api/search-records.html
+                     params
+                   else
+                     { criteria: "#{attr_to_zoho_key(params.keys.first)}:equals:#{params.values.first}" }
+                   end
+        end
+
         body = get(path, params)
         response = build_response(body)
 
@@ -59,6 +70,14 @@ module ZohoHub
         new(params).save
       end
 
+      def update(id, params)
+        new(id: id).update(params)
+      end
+
+      def blueprint_transition(id, transition_id, data = {})
+        new(id: id).blueprint_transition(transition_id, data)
+      end
+
       def all(params = {})
         params[:page] ||= DEFAULT_PAGE
         params[:per_page] ||= DEFAULT_RECORDS_PER_PAGE
@@ -85,6 +104,10 @@ module ZohoHub
 
         raise InvalidTokenError, response.msg if response.invalid_token?
         raise RecordInvalid, response.msg if response.invalid_data?
+        raise InvalidModule, response.msg if response.invalid_module?
+        raise NoPermission, response.msg if response.no_permission?
+        raise MandatoryNotFound, response.msg if response.mandatory_not_found?
+        raise RecordInBlueprint, response.msg if response.record_in_blueprint?
 
         response
       end
@@ -110,6 +133,18 @@ module ZohoHub
       response.data.first.dig(:details, :id)
     end
 
+    def update(params)
+      zoho_params = Hash[params.map { |k, v| [attr_to_zoho_key(k), v] }]
+      body = put(File.join(self.class.request_path, id), data: [zoho_params])
+      build_response(body)
+    end
+
+    def blueprint_transition(transition_id, data = {})
+      body = put(File.join(self.class.request_path, id, 'actions/blueprint'),
+                 blueprint: [{ transition_id: transition_id, data: data }])
+      build_response(body)
+    end
+
     def new_record?
       !id
     end

data/lib/zoho_hub/connection.rb

@@ -9,6 +9,18 @@ require 'zoho_hub/response'
 
 module ZohoHub
   class Connection
+    class << self
+      def infer_api_domain
+        case ZohoHub.configuration.api_domain
+        when 'https://accounts.zoho.com'    then 'https://www.zohoapis.com'
+        when 'https://accounts.zoho.com.cn' then 'https://www.zohoapis.com.cn'
+        when 'https://accounts.zoho.in'     then 'https://www.zohoapis.in'
+        when 'https://accounts.zoho.eu'     then 'https://www.zohoapis.eu'
+        else DEFAULT_DOMAIN
+        end
+      end
+    end
+
     attr_accessor :debug, :access_token, :expires_in, :api_domain, :refresh_token
 
     # This is a block to be run when the token is refreshed. This way you can do whatever you want
@@ -19,10 +31,10 @@ module ZohoHub
 
     BASE_PATH = '/crm/v2/'
 
-    def initialize(access_token:, api_domain: DEFAULT_DOMAIN, expires_in: 3600, refresh_token: nil)
+    def initialize(access_token:, api_domain: nil, expires_in: 3600, refresh_token: nil)
       @access_token = access_token
       @expires_in = expires_in
-      @api_domain = api_domain
+      @api_domain = api_domain || self.class.infer_api_domain
       @refresh_token ||= refresh_token # do not overwrite if it's already set
     end
 

data/lib/zoho_hub/errors.rb

@@ -10,6 +10,18 @@ module ZohoHub
   class InvalidTokenError < StandardError
   end
 
+  class InvalidModule < StandardError
+  end
+
+  class NoPermission < StandardError
+  end
+
+  class MandatoryNotFound < StandardError
+  end
+
+  class RecordInBlueprint < StandardError
+  end
+
   class ZohoAPIError < StandardError
   end
 end

data/lib/zoho_hub/response.rb

@@ -7,22 +7,31 @@ module ZohoHub
     end
 
     def invalid_data?
-      return false if data.is_a?(Array)
-
-      data[:code] == 'INVALID_DATA'
+      error_code?('INVALID_DATA')
     end
 
-    # {:code=>"INVALID_TOKEN", :details=>{}, :message=>"invalid oauth token", :status=>"error"}
     def invalid_token?
-      return false if data.is_a?(Array)
-
-      data[:code] == 'INVALID_TOKEN'
+      error_code?('INVALID_TOKEN')
     end
 
     def authentication_failure?
-      return false if data.is_a?(Array)
+      error_code?('AUTHENTICATION_FAILURE')
+    end
+
+    def invalid_module?
+      error_code?('INVALID_MODULE')
+    end
+
+    def no_permission?
+      error_code?('NO_PERMISSION')
+    end
 
-      data[:code] == 'AUTHENTICATION_FAILURE'
+    def mandatory_not_found?
+      error_code?('MANDATORY_NOT_FOUND')
+    end
+
+    def record_in_blueprint?
+      error_code?('RECORD_IN_BLUEPRINT')
     end
 
     def empty?
@@ -35,12 +44,13 @@ module ZohoHub
     end
 
     def msg
-      msg = data[:message]
+      first_data = data.is_a?(Array) ? data.first : data
+      msg = first_data[:message]
 
-      if data.dig(:details, :expected_data_type)
-        expected = data.dig(:details, :expected_data_type)
-        field = data.dig(:details, :api_name)
-        parent_api_name = data.dig(:details, :parent_api_name)
+      if first_data.dig(:details, :expected_data_type)
+        expected = first_data.dig(:details, :expected_data_type)
+        field = first_data.dig(:details, :api_name)
+        parent_api_name = first_data.dig(:details, :parent_api_name)
 
         msg << ", expected #{expected} for '#{field}'"
         msg << " in #{parent_api_name}" if parent_api_name
@@ -48,5 +58,17 @@ module ZohoHub
 
       msg
     end
+
+    # error response examples:
+    # {"data":[{"code":"INVALID_DATA","details":{},"message":"the id given seems to be invalid","status":"error"}]}
+    # {:code=>"INVALID_TOKEN", :details=>{}, :message=>"invalid oauth token", :status=>"error"}
+    def error_code?(code)
+      if data.is_a?(Array)
+        return false if data.size > 1
+        return data.first[:code] == code
+      end
+
+      data[:code] == code
+    end
   end
 end

data/lib/zoho_hub/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZohoHub
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/zoho_hub/with_attributes.rb

@@ -43,6 +43,11 @@ module ZohoHub
         @attribute_translation = translation
       end
 
+      def attr_to_zoho_key(attr_name)
+       return attribute_translation[attr_name.to_sym] if attribute_translation.key?(attr_name.to_sym)
+       attr_name.to_s.split('_').map(&:capitalize).join('_').to_sym
+      end
+
       def zoho_key_translation
         @attribute_translation.to_a.map(&:rotate).to_h
       end
@@ -53,14 +58,24 @@ module ZohoHub
       self.class.attributes
     end
 
-    private
+    # This method and the correponding private methods are inspired from Rails ActiveModel
+    # github.com/rails/rails/blob/master/activemodel/lib/active_model/attribute_assignment.rb
+    def assign_attributes(new_attributes)
+      unless new_attributes.is_a?(Hash)
+        raise ArgumentError, "When assigning attributes, you must pass a hash as an argument"
+      end
+      return if new_attributes.empty?
 
-    def attr_to_zoho_key(attr_name)
-      translations = self.class.attribute_translation
+      attributes = Hash[new_attributes.map { |k, v| [k.to_s, v] }]
+      attributes.each do |k, v|
+        assign_attribute(k, v)
+      end
+    end
 
-      return translations[attr_name.to_sym] if translations.key?(attr_name.to_sym)
+    private
 
-      attr_name.to_s.split('_').map(&:capitalize).join('_').to_sym
+    def attr_to_zoho_key(attr_name)
+      self.class.attr_to_zoho_key(attr_name)
     end
 
     def zoho_key_to_attr(zoho_key)
@@ -70,5 +85,14 @@ module ZohoHub
 
       zoho_key.to_sym
     end
+
+    def assign_attribute(k, v)
+      setter = :"#{k}="
+      if respond_to?(setter)
+        public_send(setter, v)
+      else
+        raise ArgumentError, "Unknown attribute #{k}"
+      end
+    end
   end
 end

data/lib/zoho_hub/with_connection.rb

@@ -21,7 +21,7 @@ module ZohoHub
       end
 
       def delete(path, params = {})
-        ZohoHub.connection.delete(path, params.to_json)
+        ZohoHub.connection.delete(path, params)
       end
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zoho_hub
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ricardo Otero
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-05 00:00:00.000000000 Z
+date: 2019-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable