active_call-zoho_crm 0.1.0

data/lib/zoho_crm/concerns/enumerable.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ZohoCrm::Enumerable
+  extend ActiveSupport::Concern
+
+  included do
+    include Enumerable
+
+    attr_reader :path, :list_key, :facade_klass, :page, :per_page
+
+    validates :path, :list_key, :facade_klass, presence: true
+    validates :page, :per_page, presence: true, numericality: { greater_than_or_equal_to: 1 }
+  end
+
+  def initialize(path:, list_key:, facade_klass:, page: 1, per_page: Float::INFINITY)
+    @path         = path
+    @list_key     = list_key
+    @facade_klass = facade_klass
+    @page         = page
+    @per_page     = per_page
+  end
+
+  def call
+    self
+  end
+
+  def each
+    return to_enum(:each) unless block_given?
+    return if invalid?
+
+    total = 0
+
+    catch :list_end do
+      loop do
+        @response = connection.get(path, params)
+        validate(:response)
+
+        unless success?
+          raise exception_for(response, errors) if bang?
+
+          throw :list_end
+        end
+
+        throw :list_end unless response.body
+
+        response.body[list_key].each do |hash|
+          yield facade_klass.new(hash)
+          total += 1
+          throw :list_end if total >= per_page
+        end
+
+        break unless response.body.dig('info', 'more_records')
+
+        @_params[:page] = response.body.dig('info', 'page') + 1
+      end
+    end
+  end
+
+  private
+
+  def params
+    @_params ||= { page: page, per_page: max_per_page_per_request }
+  end
+
+  def max_per_page_per_request
+    @_max_per_page_per_request ||= per_page.infinite? ? 100 : [per_page, 100].min
+  end
+end

data/lib/zoho_crm/error.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ZohoCrm
+  class Error < StandardError; end
+
+  class ValidationError < Error
+    include ActiveCall::ValidationErrorable
+  end
+
+  class RequestError < Error
+    include ActiveCall::RequestErrorable
+  end
+
+  # 400..499
+  class ClientError < RequestError; end
+
+  # 400
+  class BadRequestError < ClientError; end
+
+  # 401
+  class UnauthorizedError < ClientError; end
+
+  # 403
+  class ForbiddenError < ClientError; end
+
+  # 404
+  class NotFoundError < ClientError; end
+
+  # 405
+  class MethodNotAllowedError < ClientError; end
+
+  # 406
+  class NotAcceptableError < ClientError; end
+
+  # 407
+  class ProxyAuthenticationRequiredError < ClientError; end
+
+  # 408
+  class RequestTimeoutError < ClientError; end
+
+  # 409
+  class ConflictError < ClientError; end
+
+  # 410
+  class GoneError < ClientError; end
+
+  # 413
+  class PayloadTooLargeError < ClientError; end
+
+  # 415
+  class UnsupportedMediaTypeError < ClientError; end
+
+  # 422
+  class UnprocessableEntityError < ClientError; end
+
+  # 429
+  class TooManyRequestsError < ClientError; end
+
+  # 500..599
+  class ServerError < RequestError; end
+
+  # 500
+  class InternalServerError < ServerError; end
+
+  # 501
+  class NotImplementedError < ServerError; end
+
+  # 502
+  class BadGatewayError < ServerError; end
+
+  # 503
+  class ServiceUnavailableError < ServerError; end
+
+  # 504
+  class GatewayTimeoutError < ServerError; end
+end

data/lib/zoho_crm/grant_token/facade.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class ZohoCrm::GrantToken::Facade
+  attr_reader :access_token, :refresh_token, :scope, :api_domain, :expires_in, :token_type
+
+  def initialize(hash)
+    @access_token  = hash['access_token']
+    @api_domain    = hash['api_domain']
+    @expires_in    = hash['expires_in']
+    @refresh_token = hash['refresh_token']
+    @scope         = hash['scope']
+    @token_type    = hash['token_type']
+  end
+end

data/lib/zoho_crm/grant_token/get_service.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+class ZohoCrm::GrantToken::GetService < ZohoCrm::BaseService
+  attr_reader :grant_token, :client_id, :client_secret
+
+  skip_callback :call, :before, :set_access_token
+
+  after_call :set_facade
+
+  delegate_missing_to :@facade
+  delegate :refresh_token, to: :@facade, allow_nil: true
+
+  validates :grant_token, presence: true
+
+  def initialize(grant_token:, client_id: nil, client_secret: nil)
+    @grant_token   = grant_token
+    @client_id     = client_id.presence || ZohoCrm::BaseService.client_id
+    @client_secret = client_secret.presence || ZohoCrm::BaseService.client_secret
+  end
+
+  # Get refresh token from grant token.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoCrm::GrantToken::GetService.call(grant_token: '', client_id: '', client_secret: '')
+  #   service.refresh_token # => '1000.xxxx.yyyy'
+  #   service.expires_in # => 3600
+  #
+  # POST /oauth/v2/token
+  def call
+    connection.post('oauth/v2/token', params.to_param)
+  end
+
+  private
+
+  def connection
+    @_connection ||= Faraday.new do |conn|
+      conn.url_prefix = 'https://accounts.zoho.com'
+      conn.request :retry
+      conn.response :json
+      conn.response :logger, logger, **logger_options do |logger|
+        logger.filter(/(code|client_id|client_secret)=([^&]+)/i, '\1=[FILTERED]')
+        logger.filter(/"access_token":"([^"]+)"/i, '"access_token":"[FILTERED]"')
+        logger.filter(/"refresh_token":"([^"]+)"/i, '"refresh_token":"[FILTERED]"')
+      end
+      conn.adapter Faraday.default_adapter
+    end
+  end
+
+  def params
+    {
+      client_id:     client_id,
+      client_secret: client_secret,
+      code:          grant_token,
+      grant_type:    'authorization_code'
+    }
+  end
+
+  def set_facade
+    @facade = ZohoCrm::GrantToken::Facade.new(response.body)
+  end
+
+  def unauthorized?
+    response.status == 200 && response.body.key?('error')
+  end
+end

data/lib/zoho_crm/organization/facade.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class ZohoCrm::Organization::Facade
+  attr_reader :id, :attributes
+
+  def initialize(hash)
+    @id         = hash['org'][0]['id']
+    @attributes = hash['org'][0]
+  end
+end

data/lib/zoho_crm/organization/get_service.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class ZohoCrm::Organization::GetService < ZohoCrm::BaseService
+  after_call :set_facade
+
+  delegate_missing_to :@facade
+
+  # Get a document.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoCrm::Organization::GetService.call
+  #
+  #   service.success? # => true
+  #   service.errors # => #<ActiveModel::Errors []>
+  #
+  #   service.response # => #<Faraday::Response ...>
+  #   service.response.status # => 200
+  #   service.response.body # => {}
+  #
+  #   service.facade # => #<ZohoCrm::Organization::Facade ...>
+  #   service.facade.attributes
+  #   service.attributes
+  #
+  # GET /crm/v7/org
+  def call
+    connection.get('org')
+  end
+
+  private
+
+  def set_facade
+    @facade = ZohoCrm::Organization::Facade.new(response.body)
+  end
+end

data/lib/zoho_crm/record/create_service.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+class ZohoCrm::Record::CreateService < ZohoCrm::BaseService
+  attr_reader :module_name, :data
+
+  validates :module_name, :data, presence: true
+
+  after_call :set_facade
+
+  delegate_missing_to :@facade
+
+  def initialize(module_name:, data:)
+    @module_name = module_name
+    @data        = data.is_a?(Array) ? data : [data]
+  end
+
+  # Create a record.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoCrm::Record::CreateService.call(
+  #     module_name: 'Contacts',
+  #     data: {
+  #       'Email' => 'eric.cartman@example.com',
+  #       'First_Name' => 'Eric',
+  #       'Last_Name' => 'Cartman'
+  #     }
+  #   )
+  #
+  #   service.success? # => true
+  #   service.errors # => #<ActiveModel::Errors []>
+  #
+  #   service.response # => #<Faraday::Response ...>
+  #   service.response.status # => 201
+  #   service.response.body # => {}
+  #
+  #   service.facade # => #<ZohoCrm::Record::Facade ...>
+  #   service.facade.attributes
+  #   service.attributes
+  #
+  # POST /crm/v7/:module_name
+  def call
+    connection.post(module_name, **params)
+  end
+
+  private
+
+  def params
+    {
+      data: data
+    }
+  end
+
+  def set_facade
+    @facade = ZohoCrm::Record::Facade.new(response.body)
+  end
+end

data/lib/zoho_crm/record/delete_service.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class ZohoCrm::Record::DeleteService < ZohoCrm::BaseService
+  attr_reader :module_name, :id
+
+  validates :module_name, :id, presence: true
+
+  after_call :set_facade
+
+  delegate_missing_to :@facade
+
+  def initialize(module_name:, id:)
+    @module_name = module_name
+    @id          = id
+  end
+
+  # Delete a record.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoCrm::Record::DeleteService.call(module_name: 'Contacts', id: '')
+  #
+  #   service.success? # => true
+  #   service.errors # => #<ActiveModel::Errors []>
+  #
+  #   service.response # => #<Faraday::Response ...>
+  #   service.response.status # => 200
+  #   service.response.body # => {}
+  #
+  #   service.facade # => #<ZohoCrm::Record::Facade ...>
+  #   service.facade.attributes
+  #   service.attributes
+  #
+  # DELETE /crm/v7/:module_name/:id
+  def call
+    connection.delete("#{module_name}/#{id}")
+  end
+
+  private
+
+  def set_facade
+    @facade = ZohoCrm::Record::Facade.new(response.body)
+  end
+end

data/lib/zoho_crm/record/facade.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class ZohoCrm::Record::Facade
+  attr_reader :id, :attributes
+
+  def initialize(hash)
+    @id         = hash['data'] ? (hash['data'][0]['id'] || hash['data'][0].dig('details', 'id')) : hash['id']
+    @attributes = hash['data'] ? hash['data'][0] : hash
+  end
+end

data/lib/zoho_crm/record/get_service.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class ZohoCrm::Record::GetService < ZohoCrm::BaseService
+  attr_reader :module_name, :id
+
+  validates :module_name, :id, presence: true
+
+  after_call :set_facade
+
+  delegate_missing_to :@facade
+
+  def initialize(module_name:, id:)
+    @module_name = module_name
+    @id          = id
+  end
+
+  # Get a document.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoCrm::Record::GetService.call(module_name: 'Contacts', id: '')
+  #
+  #   service.success? # => true
+  #   service.errors # => #<ActiveModel::Errors []>
+  #
+  #   service.response # => #<Faraday::Response ...>
+  #   service.response.status # => 200
+  #   service.response.body # => {}
+  #
+  #   service.facade # => #<ZohoCrm::Record::Facade ...>
+  #   service.facade.attributes
+  #   service.attributes
+  #
+  # GET /crm/v7/:module_name/:id
+  def call
+    connection.get("#{module_name}/#{id}")
+  end
+
+  private
+
+  def set_facade
+    @facade = ZohoCrm::Record::Facade.new(response.body)
+  end
+
+  def not_found?
+    response.status == 204
+  end
+end

data/lib/zoho_crm/record/list_service.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+class ZohoCrm::Record::ListService < ZohoCrm::BaseService
+  SORT_COLUMNS = %w[id Created_Time Modified_Time].freeze
+  SORT_ORDERS  = %w[asc desc].freeze
+
+  include ZohoCrm::Enumerable
+
+  attr_reader :module_name, :fields, :sort_by, :sort_order
+
+  validates :module_name, :fields, presence: true
+  validates :sort_order, inclusion: { in: SORT_ORDERS, message: "Sort order must be one of #{SORT_ORDERS.join(', ')}" }
+
+  validates :sort_by, inclusion: {
+    in:      SORT_COLUMNS,
+    message: "Sort by must be one of #{SORT_COLUMNS.join(', ')}"
+  }
+
+  # List records.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoCrm::Record::ListService.call(module_name: 'Contacts', fields: 'Email,Last_Name').first
+  #   service.id
+  #
+  # If you don't provide the `per_page` argument, multiple API requests will be made untill all records have been
+  # returned. You could be rate limited, so use wisely.
+  #
+  #   ZohoCrm::Record::ListService.call(module_name: 'Contacts', fields: 'Email,Last_Name', page: 1, per_page: 10).each { _1 }
+  #
+  # Sort by column.
+  #
+  #   ZohoCrm::Record::ListService.call(module_name: 'Contacts', fields: 'Email,Last_Name', sort_by: 'id', sort_order: 'asc').map { _1 }
+  #
+  # Columns to sort by are `id`, `Created_Time` and `Modified_Time`.
+  #
+  # GET /crm/v7/:module_name
+  def initialize(module_name:, fields:, page: 1, per_page: Float::INFINITY, sort_by: 'id', sort_order: 'desc')
+    @module_name = module_name
+    @fields      = fields
+    @sort_by     = sort_by
+    @sort_order  = sort_order
+
+    super(
+      path:         module_name,
+      list_key:     'data',
+      facade_klass: ZohoCrm::Record::Facade,
+      page:         page,
+      per_page:     per_page
+    )
+  end
+
+  private
+
+  def params
+    @_params ||= {
+      page:       page,
+      per_page:   max_per_page_per_request,
+      sort_by:    sort_by,
+      sort_order: sort_order,
+      fields:     fields
+    }
+  end
+end

data/lib/zoho_crm/record/search_service.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+class ZohoCrm::Record::SearchService < ZohoCrm::BaseService
+  SORT_COLUMNS = %w[id Created_Time Modified_Time].freeze
+  SORT_ORDERS  = %w[asc desc].freeze
+
+  include ZohoCrm::Enumerable
+
+  attr_reader :module_name, :sort_by, :sort_order, :email, :phone, :criteria, :word
+
+  validates :module_name, presence: true
+  validates :sort_order, inclusion: { in: SORT_ORDERS, message: "Sort order must be one of #{SORT_ORDERS.join(', ')}" }
+
+  validates :sort_by, inclusion: {
+    in:      SORT_COLUMNS,
+    message: "Sort by must be one of #{SORT_COLUMNS.join(', ')}"
+  }
+
+  # List records.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoCrm::Record::SearchService.call(module_name: 'Contacts', email: 'eric.cartman@example.com').first
+  #   service.id
+  #
+  # If you don't provide the `per_page` argument, multiple API requests will be made untill all records have been
+  # returned. You could be rate limited, so use wisely.
+  #
+  #   ZohoCrm::Record::SearchService.call(module_name: 'Contacts', email: 'eric.cartman@example.com', page: 1, per_page: 10).each { _1 }
+  #
+  # Sort by column.
+  #
+  #   ZohoCrm::Record::SearchService.call(module_name: 'Contacts', email: 'eric.cartman@example.com', sort_by: 'Modified_Time', sort_order: 'asc').map { _1 }
+  #
+  # Columns to sort by are `id`, `Created_Time` and `Modified_Time`.
+  #
+  # Search by email.
+  #
+  #   ZohoCrm::Record::SearchService.call(module_name: 'Contacts', email: 'eric.cartman@example.com').map { _1 }
+  #
+  # Search by phone.
+  #
+  #   ZohoCrm::Record::SearchService.call(module_name: 'Contacts', phone: '0123456789').map { _1 }
+  #
+  # Search by criteria.
+  #
+  #   ZohoCrm::Record::SearchService.call(module_name: 'Contacts', criteria: 'Created_Time:between:2025-01-01T06:00:00+00:00,2025-01-30T06:00:00+00:00').map { _1 }
+  #
+  # Search by word.
+  #
+  #   ZohoCrm::Record::SearchService.call(module_name: 'Contacts', word: 'eric').map { _1 }
+  #
+  # GET /crm/v7/:module_name
+  def initialize(module_name:, page: 1, per_page: Float::INFINITY, sort_by: 'id', sort_order: 'desc', email: nil, phone: nil, criteria: nil, word: nil)
+    @module_name = module_name
+    @sort_by     = sort_by
+    @sort_order  = sort_order
+    @email       = email
+    @phone       = phone
+    @criteria    = criteria
+    @word        = word
+
+    super(
+      path:         "#{module_name}/search",
+      list_key:     'data',
+      facade_klass: ZohoCrm::Record::Facade,
+      page:         page,
+      per_page:     per_page
+    )
+  end
+
+  private
+
+  def params
+    @_params ||= {
+      page:       page,
+      per_page:   max_per_page_per_request,
+      sort_by:    sort_by,
+      sort_order: sort_order,
+      email:      email,
+      phone:      phone,
+      criteria:   criteria,
+      word:       word
+    }.compact_blank
+  end
+end

data/lib/zoho_crm/record/update_service.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+class ZohoCrm::Record::UpdateService < ZohoCrm::BaseService
+  attr_reader :module_name, :data
+
+  validates :module_name, :data, presence: true
+
+  after_call :set_facade
+
+  delegate_missing_to :@facade
+
+  def initialize(module_name:, data:)
+    @module_name = module_name
+    @data        = data.is_a?(Array) ? data : [data]
+  end
+
+  # Create a record.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoCrm::Record::UpdateService.call(
+  #     module_name: 'Contacts',
+  #     data: {
+  #       'id' => '',
+  #       'First_Name' => 'Eric Theodore'
+  #     }
+  #   )
+  #
+  #   service.success? # => true
+  #   service.errors # => #<ActiveModel::Errors []>
+  #
+  #   service.response # => #<Faraday::Response ...>
+  #   service.response.status # => 200
+  #   service.response.body # => {}
+  #
+  #   service.facade # => #<ZohoCrm::Record::Facade ...>
+  #   service.facade.attributes
+  #   service.attributes
+  #
+  # PUT /crm/v7/:module_name
+  def call
+    connection.put(module_name, **params)
+  end
+
+  private
+
+  def params
+    {
+      data: data
+    }
+  end
+
+  def set_facade
+    @facade = ZohoCrm::Record::Facade.new(response.body)
+  end
+end