zoho_hub 0.3.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1967126d56677efb3373c3a3d8700842f5d03e0f3b0cb922b4ffcf5d113a831
-  data.tar.gz: 1cf0f3e67da7d878dd367614c3da7441d0024fe070dae978f72e49575e6be013
+  metadata.gz: d69358949e8262ad9da808101b0bbb2da5d0eae262d2d34ab032e5097d58f5ba
+  data.tar.gz: a0b64a4714925fa5a6392e43ecd991aaf71e9b3991e4505a5d2703bca22f8269
 SHA512:
-  metadata.gz: 203045fd8b960ae3dd03873106ea7a88a111bbd6618d9942e9c597cdef83ba860792639e13e92b7a32ad0d550b9521795ab8c4043dc8e9e2de44321a5e2a7990
-  data.tar.gz: ac2a1e1e7bca5a28196d9cdc68312c1a8774ddc1666266a0a4956587b482bf255da15aa50f9c05cb593a6768103f3b939a91ed692c16641cd26976ce51f63243
+  metadata.gz: d02305e21aae61e11f09a010b8f22dab327af638b036ca075abb47e0943eaad1870355e976c208b00c9a5dfa87f05ff82f60754fd50f1eccee97e37a7e3c8967
+  data.tar.gz: 756fb2bd03d39e70f46fdc04eb34bea1310701b72ba363a3b6c79fab033ccf5defa2b615edcae9af6c86cae45dacf24bcefd59c3c17ff2a4c3b7456f0595b0ed

data/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '2.5'
+          bundler-cache: true
+      - name: rubocop version
+        timeout-minutes: 1
+        run: bundle exec rubocop --version
+      - name: rubocop
+        timeout-minutes: 5
+        run: bundle exec rubocop -c .rubocop.yml
+
+  test:
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.experimental }}
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['2.5', '2.6', '2.7', '3.0']
+        experimental: [false]
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{matrix.ruby}}
+          bundler-cache: true
+      - name: Run tests
+        timeout-minutes: 5
+        run: ${{matrix.env}} bundle exec rspec

data/.rubocop.yml

@@ -3,6 +3,13 @@ require: rubocop-rspec
 AllCops:
   TargetRubyVersion: 2.5.1
 
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+Lint:
+  Exclude:
+    - bin/*
+
 # Don't force top level comments in every class
 Style/Documentation:
   Enabled: false
@@ -25,6 +32,12 @@ Metrics/ClassLength:
 Metrics/MethodLength:
   Max: 20
 
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
 Metrics/AbcSize:
   Max: 30
 

data/.ruby-version

@@ -1 +1 @@
-2.5.3
+2.7.6

data/README.md

@@ -1,10 +1,9 @@
 # ZohoHub
 
-[![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 +11,38 @@ 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
+
+- [ZohoHub](#zohohub)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+  - [Setup process](#setup-process)
+    - [1. Register your application](#1-register-your-application)
+      - [1.1 Zoho Accounts URL](#11-zoho-accounts-url)
+      - [1.2 Authorized Redirect URI](#12-authorized-redirect-uri)
+    - [2. Configure ZohoHub with your credentials](#2-configure-zohohub-with-your-credentials)
+    - [3. Authorization request](#3-authorization-request)
+      - [3.1 Redirection based authentication](#31-redirection-based-authentication)
+      - [3.2 Self-Client Authorization](#32-self-client-authorization)
+      - [3.3 More on scopes](#33-more-on-scopes)
+      - [3.4 Offline access](#34-offline-access)
+    - [4. Access token](#4-access-token)
+    - [5. Refresh token](#5-refresh-token)
+    - [6. Basic ZohoHub flow](#6-basic-zohohub-flow)
+    - [7. BaseRecord and record classes](#7-baserecord-and-record-classes)
+      - [7.1 Reflection](#71-reflection)
+      - [7.2 Subclassing BaseRecord](#72-subclassing-baserecord)
+  - [8 Notifications](#8-notifications)
+    - [8.1 Enable notifications](#81-enable-notifications)
+    - [8.2 List notifications](#82-list-notifications)
+    - [8.3 Caveats](#83-caveats)
+  - [Tips and suggestions](#tips-and-suggestions)
+  - [Examples](#examples)
+    - [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 +66,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:
 
-* EU: https://accounts.zoho.eu
-* US: https://accounts.zoho.com
-* China: https://accounts.zoho.com.cn
+- China: https://accounts.zoho.com.cn
+- EU: https://accounts.zoho.eu
+- India: https://accounts.zoho.in
+- US: https://accounts.zoho.com
 
-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,17 +88,20 @@ 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
 
-> **Note:** Treat these credentials like an important password. It is *strongly* recommended to not
-> paste them anywhere in plain text. Do *not* add them to version control; keep them out of your
+> **Note:** Treat these credentials like an important password. It is _strongly_ recommended to not
+> paste them anywhere in plain text. Do _not_ add them to version control; keep them out of your
 > 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 +114,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 +132,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 +148,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
@@ -127,11 +167,13 @@ 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'])
+ZohoHub::Auth.auth_url(scopes: ['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"
 ```
 
-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 +181,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 +194,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,10 +207,15 @@ 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
+This gem automatically refresh the access token.
+
+If you want automatic refresh, use the `refresh_token` argument as in the next chapter.
+
+---
 
 ### 6. Basic ZohoHub flow
 
@@ -176,7 +225,8 @@ token**, setup a ZohoHub connection:
 ```ruby
 ZohoHub.setup_connection access_token: 'ACCESS_TOKEN',
                          expires_in: 'EXPIRES_IN_SEC',
-                         api_domain: 'API_DOMAIN'
+                         api_domain: 'API_DOMAIN',
+                         refresh_token: 'REFRESH_TOKEN'
 ```
 
 Now you can issue requests to Zoho's API with the Connection object, e.g.:
@@ -186,7 +236,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 +261,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,44 +271,231 @@ Specify this module's fields as attributes:
 ```ruby
 # lead.rb
 
-class Lead < BaseRecord
-  attributes: :id, :first_name, :last_name, :phone, :email, :source, # etc.
+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
+
+# Or in one step:
+lead = Lead.create(first_name: 'First name', ...)
+```
+
+Updating records:
+
+```ruby
+Lead.update(id: lead.id, first_name: "...", last_name: "...")
+
+# Or
+lead.update(first_name: "...", last_name: "...")
+
+# Or update up to 100 records in one call:
+leads = [{ id: id1, phone: "123" }, { id: id2, first_name: "..." }]
+Lead.update_all(leads)
+```
+
+Blueprint transition:
+
+```ruby
+Lead.blueprint_transition(lead.id, transition_id)
+
+# Or
+lead.blueprint_transition(transition_id)
+```
+
+Adding notes:
+
+```ruby
+Lead.add_note(id: lead.id, title: 'Note title', content: 'Note content')
+```
+
+Related records:
+
+```ruby
+Product.all_related(parent_module: 'Lead', parent_id: lead.id)
+Product.add_related(
+  parent_module: 'Lead',
+  parent_id: lead.id,
+  related_id: product.id
+)
+Product.remove_related(
+  parent_module: 'Lead',
+  parent_id: lead.id,
+  related_id: product.id
+)
+Product.update_related(...)
+```
+
+Attachments (`ZohoHub::Attachment` is defined in the gem):
+
+```ruby
+Lead.related_attachments(parent_id: lead.id)
+# -> Array of Attachments
+
+attachment = Lead.download_attachment(parent_id: lead.id, attachment_id:attachment.id)
+# -> Attachment (attachment.file contains the file as a Tempfile)
+
+#NB: Lead.upload_attachment not implemented yet
+```
+
+## 8 Notifications
+
+Zoho allows you to receive a notification when a record of a module changes. Supported operation types are create, delete, edit, all.
+
+### 8.1 Enable notifications
+
+In order to receive notifications, you have to enable them first.
+
+```ruby
+# Enable notifications for a given channel:
+notification_url = 'https://example.org/api/notifications' # Zoho will send notifications by POST to this url
+token = '123abc' # Zoho will send this token back to you, so you can ensure that the notification is from Zoho
+channel_id = 1 # Choose a channel to handle the response
+events = %w[Leads.create Deals.edit Contacts.delete Sales_Orders.all] # Which events to receive notifications for
+channel_expiry = (DateTime.now + 1.day).iso8601 # choose a date when the channel should expire. 24h is the maximum, default is one hour
+
+ZohoHub::Notifications.enable(notification_url, channel_id, events, channel_expiry, token)
+```
+
+After enabling notifications, Zoho will execute a POST request to the provided notification_url every time the requested event occurs.
+
+For a list of an in-depth description of the response, check the [Zoho documentation](https://www.zoho.com/crm/developer/docs/api/notifications/overview.html)
+
+### 8.2 List notifications
+
+You can also retrieve all notifications that are currently enabled and that you are receiving uppdates for.
+
+```ruby
+# Get all enabled notifications
+ZohoHub::Notifications.all
 ```
 
+### 8.3 Caveats
+
+- Zoho does not notify you when records are merged.
+- Since Zoho does not tell you what changed, you will have to request the record by yourself. Due to this you can miss changes, when they occur quickly after another. This is especially important for status changes, as you might miss state changes.
+
 ## Tips and suggestions
 
-* Using a tool such as Postman or curl to issue HTTP requests and verify responses in isolation
+- Using a tool such as Postman or curl to issue HTTP requests and verify responses in isolation
   can be a great sanity check during setup.
-* Downloading ZohoHub code (as opposed to the gem) and running `bin/console` is a great way to
+- Downloading ZohoHub code (as opposed to the gem) and running `bin/console` is a great way to
   learn how the code works and test aspects of setup and Zoho's API in isolation.
-* [The Zoho API Documentation](https://www.zoho.com/crm/help/developer/api/overview.html) is your
+- [The Zoho API Documentation](https://www.zoho.com/crm/help/developer/api/overview.html) is your
   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)
+- If you're manually implementing your record classes (rather than using the reflection mechanism),
+  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 +510,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/bin/console

@@ -20,7 +20,7 @@ puts 'Refreshing token...'
 token_params = ZohoHub::Auth.refresh_token(ENV['ZOHO_REFRESH_TOKEN'])
 ZohoHub.setup_connection(token_params)
 
-self.send(:include, ZohoHub)
+send(:include, ZohoHub)
 
 require 'pry'
 Pry.start

data/examples/models/potential.rb

@@ -28,6 +28,8 @@ module ZohoHub
     )
 
     def initialize(params = {})
+      super
+
       attributes.each do |attr|
         zoho_key = attr_to_zoho_key(attr)
 

data/lib/zoho_hub/auth.rb

@@ -20,6 +20,7 @@ module ZohoHub
       ZohoCRM.settings.all
       ZohoCRM.modules.contacts.all
       ZohoCRM.modules.all
+      ZohoCRM.notifications.all
     ].freeze
 
     DEFAULT_ACCESS_TYPE = 'offline'

data/lib/zoho_hub/base_record.rb

@@ -12,7 +12,7 @@ module ZohoHub
     include WithAttributes
     include WithValidations
 
-    # Default nnumber of records when fetching all.
+    # Default number of records when fetching all.
     DEFAULT_RECORDS_PER_PAGE = 200
 
     # Default page number when fetching all.
@@ -42,6 +42,21 @@ 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
+                     key = attr_to_zoho_key(params.keys.first)
+
+                     {
+                       criteria: "#{key}:equals:#{params.values.first}"
+                     }
+                   end
+        end
+
         body = get(path, params)
         response = build_response(body)
 
@@ -59,6 +74,61 @@ 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 blueprint_transitions(id)
+        new(id: id).blueprint_transitions
+      end
+
+      def add_note(id:, title: '', content: '')
+        path = File.join(request_path, id, 'Notes')
+        post(path, data: [{ Note_Title: title, Note_Content: content }])
+      end
+
+      def all_related(parent_module:, parent_id:)
+        body = get(File.join(parent_module.constantize.request_path, parent_id, request_path))
+        response = build_response(body)
+
+        data = response.nil? ? [] : response.data
+
+        data.map { |json| new(json) }
+      end
+
+      def update_related(parent_module:, parent_id:, related_id:, data:)
+        path = File.join(
+          parent_module.constantize.request_path, parent_id, request_path, related_id
+        )
+        body = put(path, data: data)
+        build_response(body)
+      end
+
+      def add_related(parent_module:, parent_id:, related_id:)
+        update_related(
+          parent_module: parent_module, parent_id: parent_id, related_id: related_id, data: [{}]
+        )
+      end
+
+      def remove_related(parent_module:, parent_id:, related_id:)
+        body = delete(
+          File.join(parent_module.constantize.request_path, parent_id, request_path, related_id)
+        )
+        build_response(body)
+      end
+
+      def update_all(records)
+        zoho_params = records.map { |record| record.transform_keys { |key| attr_to_zoho_key(key) } }
+
+        body = put(File.join(request_path), data: zoho_params)
+
+        build_response(body)
+      end
+
       def all(params = {})
         params[:page] ||= DEFAULT_PAGE
         params[:per_page] ||= DEFAULT_RECORDS_PER_PAGE
@@ -84,7 +154,12 @@ module ZohoHub
         response = Response.new(body)
 
         raise InvalidTokenError, response.msg if response.invalid_token?
+        raise InternalError, response.msg if response.internal_error?
         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
@@ -93,8 +168,9 @@ module ZohoHub
     def initialize(params = {})
       attributes.each do |attr|
         zoho_key = attr_to_zoho_key(attr)
+        value = params[zoho_key].nil? ? params[attr] : params[zoho_key]
 
-        send("#{attr}=", params[zoho_key] || params[attr])
+        send("#{attr}=", value)
       end
     end
 
@@ -110,6 +186,25 @@ module ZohoHub
       response.data.first.dig(:details, :id)
     end
 
+    def update(params)
+      zoho_params = params.transform_keys { |key| attr_to_zoho_key(key) }
+      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 blueprint_transitions
+      body = get(File.join(self.class.request_path, id, 'actions/blueprint'))
+      build_response(body)
+    end
+
     def new_record?
       !id
     end

data/lib/zoho_hub/cli/callback_server.rb

@@ -62,7 +62,7 @@ module ZohoHub
         url = ZohoHub::Auth.auth_url
         Launchy.open(url)
 
-        puts "Running callback server...."
+        puts 'Running callback server....'
         ZohoHub::OauthCallbackServer.run!
       end
 
@@ -79,13 +79,13 @@ module ZohoHub
       def parse(argv, _env)
         parser.parse!(argv)
         true
-      rescue OptionParser::ParseError => error
-        error_output(error)
+      rescue OptionParser::ParseError => e
+        error_output(e)
       end
 
       def error_output(error)
-        $stderr.puts "Error: #{error}"
-        $stderr.puts "Try `#{parser.program_name} server --help' for more information"
+        warn "Error: #{error}"
+        warn "Try `#{parser.program_name} server --help' for more information"
 
         false
       end

data/lib/zoho_hub/cli/read_modules.rb

@@ -107,13 +107,13 @@ module ZohoHub
       def parse(argv, _env)
         parser.parse!(argv)
         true
-      rescue OptionParser::ParseError => error
-        error_output(error)
+      rescue OptionParser::ParseError => e
+        error_output(e)
       end
 
       def error_output(error)
-        $stderr.puts "Error: #{error}"
-        $stderr.puts "Try `#{parser.program_name} server --help' for more information"
+        warn "Error: #{error}"
+        warn "Try `#{parser.program_name} server --help' for more information"
 
         false
       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: nil, 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
 
@@ -76,7 +88,7 @@ module ZohoHub
       response = Response.new(http_response.body)
 
       # Try to refresh the token and try again
-      if response.invalid_token? && refresh_token?
+      if (response.invalid_token? || response.authentication_failure?) && refresh_token?
         log "Refreshing outdated token... #{@access_token}"
         params = ZohoHub::Auth.refresh_token(@refresh_token)
 
@@ -104,6 +116,7 @@ module ZohoHub
     def adapter
       Faraday.new(url: base_url) do |conn|
         conn.headers = authorization_header if access_token?
+        conn.use FaradayMiddleware::EncodeJson
         conn.use FaradayMiddleware::ParseJson
         conn.response :json, parser_options: { symbolize_names: true }
         conn.response :logger if ZohoHub.configuration.debug?

data/lib/zoho_hub/errors.rb

@@ -10,6 +10,21 @@ module ZohoHub
   class InvalidTokenError < StandardError
   end
 
+  class InternalError < 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/modules/attachment.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'zoho_hub/base_record'
+
+module ZohoHub
+  class BaseRecord
+    class << self
+      def related_attachments(parent_id:)
+        body = get(File.join(request_path, parent_id, 'Attachments'))
+        response = build_response(body)
+
+        data = response.nil? ? [] : response.data
+
+        data.map { |json| Attachment.new(json) }
+      end
+
+      def download_attachment(parent_id:, attachment_id:)
+        attachment = related_attachments(parent_id: parent_id).find { |a| a.id == attachment_id }
+        uri = File.join(request_path, parent_id, 'Attachments', attachment_id)
+        res = ZohoHub.connection.adapter.get(uri)
+        attachment.content_type = res.headers['content-type']
+        extension = File.extname(attachment.file_name)
+        basename = File.basename(attachment.file_name, extension)
+        file = Tempfile.new([basename, extension])
+        file.binmode
+        file.write(res.body)
+        file.rewind
+        attachment.file = file
+        attachment
+      end
+    end
+  end
+
+  class Attachment < BaseRecord
+    attributes :id, :file_name, :created_by, :modified_by, :owner, :parent_id, :created_time,
+               :modified_time, :size
+
+    attribute_translation id: :id
+    attr_accessor :content_type, :file
+  end
+end

data/lib/zoho_hub/notifications.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'zoho_hub/response'
+require 'zoho_hub/with_connection'
+
+module ZohoHub
+  class Notifications
+    include WithConnection
+
+    # Default number 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
+        @request_path = 'actions/watch'
+      end
+
+      def all(params = {})
+        params[:page] ||= DEFAULT_PAGE
+        params[:per_page] ||= DEFAULT_RECORDS_PER_PAGE
+        params[:per_page] = MIN_RECORDS if params[:per_page] < MIN_RECORDS
+
+        body = get(request_path, params)
+        return [] if body.nil?
+
+        build_response(body)
+      end
+
+      def enable(notify_url, channel_id, events, channel_expiry = nil, token = nil)
+        body = post(request_path, watch: [{ notify_url: notify_url,
+                                            channel_id: channel_id,
+                                            events: events,
+                                            channel_expiry: channel_expiry,
+                                            token: token }])
+        build_response(body)
+      end
+
+      def build_response(body)
+        response = Response.new(body)
+
+        raise RecordInvalid, response.msg if response.invalid_data?
+        raise MandatoryNotFound, response.msg if response.mandatory_not_found?
+
+        response.data
+      end
+    end
+  end
+end

data/lib/zoho_hub/response.rb

@@ -7,22 +7,35 @@ 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)
+      error_code?('INVALID_TOKEN')
+    end
 
-      data[:code] == 'INVALID_TOKEN'
+    def internal_error?
+      error_code?('INTERNAL_ERROR')
     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?
@@ -30,17 +43,18 @@ module ZohoHub
     end
 
     def data
-      data = @params[:data] if @params.dig(:data)
+      data = @params[:data] if @params[:data]
       data || @params
     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 +62,18 @@ module ZohoHub
 
       msg
     end
+
+    # Error response examples:
+    # {"data":[{"code":"INVALID_DATA","details":{},"message":"the id given...","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/string_utils.rb

@@ -8,7 +8,7 @@ module ZohoHub
       end
 
       def pluralize(text)
-        if ENV.key?('RAILS_ENV')
+        if defined?(ActiveSupport::Inflector)
           ActiveSupport::Inflector.pluralize(text)
         else
           "#{text}s"

data/lib/zoho_hub/version.rb

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

data/lib/zoho_hub/with_attributes.rb

@@ -43,6 +43,14 @@ module ZohoHub
         @attribute_translation = translation
       end
 
+      def attr_to_zoho_key(attr_name)
+        if attribute_translation.key?(attr_name.to_sym)
+          return attribute_translation[attr_name.to_sym]
+        end
+
+        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 +61,25 @@ 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
 
-    def attr_to_zoho_key(attr_name)
-      translations = self.class.attribute_translation
+      return if new_attributes.empty?
 
-      return translations[attr_name.to_sym] if translations.key?(attr_name.to_sym)
+      attributes = new_attributes.transform_keys(&:to_s)
+      attributes.each do |k, v|
+        assign_attribute(k, v)
+      end
+    end
 
-      attr_name.to_s.split('_').map(&:capitalize).join('_').to_sym
+    private
+
+    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 +89,13 @@ module ZohoHub
 
       zoho_key.to_sym
     end
+
+    def assign_attribute(key, value)
+      setter = :"#{key}="
+
+      return public_send(setter, value) if respond_to?(setter)
+
+      raise ArgumentError, "Unknown attribute #{key}"
+    end
   end
 end

data/lib/zoho_hub/with_connection.rb

@@ -13,15 +13,15 @@ module ZohoHub
       end
 
       def post(path, params = {})
-        ZohoHub.connection.post(path, params.to_json)
+        ZohoHub.connection.post(path, params)
       end
 
       def put(path, params = {})
-        ZohoHub.connection.put(path, params.to_json)
+        ZohoHub.connection.put(path, params)
       end
 
       def delete(path, params = {})
-        ZohoHub.connection.delete(path, params.to_json)
+        ZohoHub.connection.delete(path, params)
       end
     end
 

data/lib/zoho_hub.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'backports/2.3.0/hash' if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.3.0')
+require 'backports/2.5.0/hash' if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.5.0')
 
 require 'zoho_hub/version'
 require 'zoho_hub/auth'
@@ -8,6 +9,7 @@ require 'zoho_hub/configuration'
 require 'zoho_hub/connection'
 require 'zoho_hub/errors'
 require 'zoho_hub/base_record'
+require 'zoho_hub/modules/attachment'
 require 'zoho_hub/settings/module'
 
 require 'zoho_hub/reflection/module_builder'
@@ -39,7 +41,7 @@ module ZohoHub
 
     connection_params = params.dup.slice(:access_token, :expires_in, :api_domain, :refresh_token)
 
-    @connection = Connection.new(connection_params)
+    @connection = Connection.new(**connection_params)
   end
 
   def connection

data/zoho_hub.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.1.0'
 
   spec.add_dependency 'addressable'
-  spec.add_dependency 'backports' if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.3.0')
+  spec.add_dependency 'backports'
   spec.add_dependency 'faraday'
   spec.add_dependency 'faraday_middleware'
   spec.add_dependency 'launchy'
@@ -34,6 +34,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'rainbow'
   spec.add_dependency 'sinatra'
 
+  spec.add_development_dependency 'activesupport'
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'dotenv'
   spec.add_development_dependency 'pry-byebug'
@@ -42,4 +43,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'rubocop-rspec'
   spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'webmock'
 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.2
 platform: ruby
 authors:
 - Ricardo Otero
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-05 00:00:00.000000000 Z
+date: 2022-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: backports
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +122,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -220,6 +248,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Simple gem to connect to Zoho CRM API V2
 email:
 - oterosantos@gmail.com
@@ -228,11 +270,11 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
-- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -253,6 +295,8 @@ files:
 - lib/zoho_hub/configuration.rb
 - lib/zoho_hub/connection.rb
 - lib/zoho_hub/errors.rb
+- lib/zoho_hub/modules/attachment.rb
+- lib/zoho_hub/notifications.rb
 - lib/zoho_hub/oauth_callback_server.rb
 - lib/zoho_hub/reflection/module_builder.rb
 - lib/zoho_hub/response.rb
@@ -287,8 +331,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: Simple gem to connect to Zoho CRM API V2

data/.travis.yml

@@ -1,8 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.1.10
-  - 2.2.10
-  - 2.3.7
-  - 2.4.4
-  - 2.5.3