active_call-zoho_sign 0.1.0

data/lib/zoho_sign/base_service.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+class ZohoSign::BaseService < ActiveCall::Base
+  self.abstract_class = true
+
+  CACHE_KEY = { access_token: 'zoho_sign/base_service/access_token' }.freeze
+
+  EXCEPTION_MAPPING = {
+    bad_request:                   ZohoSign::BadRequestError,
+    unauthorized:                  ZohoSign::UnauthorizedError,
+    forbidden:                     ZohoSign::ForbiddenError,
+    not_found:                     ZohoSign::NotFoundError,
+    proxy_authentication_required: ZohoSign::ProxyAuthenticationRequiredError,
+    request_timeout:               ZohoSign::RequestTimeoutError,
+    conflict:                      ZohoSign::ConflictError,
+    unprocessable_entity:          ZohoSign::UnprocessableEntityError,
+    too_many_requests:             ZohoSign::TooManyRequestsError,
+    client_error:                  ZohoSign::ClientError,
+    server_error:                  ZohoSign::ServerError
+  }.freeze
+
+  config_accessor :base_url, default: 'https://sign.zoho.com/api/v1', instance_writer: false
+  config_accessor :cache, default: ActiveSupport::Cache::MemoryStore.new, instance_writer: false
+  config_accessor :logger, default: Logger.new($stdout), instance_writer: false
+  config_accessor :log_level, default: :info, instance_writer: false
+  config_accessor :log_headers, default: false, instance_writer: false
+  config_accessor :log_bodies, default: false, instance_writer: false
+  config_accessor :client_id, :client_secret, :refresh_token, instance_writer: false
+
+  attr_reader :facade
+
+  validate on: :response do
+    throw :abort if response.is_a?(Enumerable)
+
+    errors.add(:base, :server_error) and throw :abort if response.status >= 500
+
+    errors.add(:base, :unauthorized) and throw :abort if unauthorized?
+    errors.add(:base, :forbidden) and throw :abort if forbidden?
+    errors.add(:base, :not_found) and throw :abort if not_found?
+    errors.add(:base, :proxy_authentication_required) and throw :abort if proxy_authentication_required?
+    errors.add(:base, :request_timeout) and throw :abort if request_timeout?
+    errors.add(:base, :conflict) and throw :abort if conflict?
+    errors.add(:base, :unprocessable_entity) and throw :abort if unprocessable_entity?
+    errors.add(:base, :too_many_requests) and throw :abort if too_many_requests?
+
+    # Check for bad_request here since too_many_requests also has a status of 400.
+    errors.add(:base, :bad_request) and throw :abort if bad_request?
+
+    # We'll use client_error for everything else that we don't have an explicit exception class for.
+    errors.add(:base, :client_error) and throw :abort if response.status >= 400
+  end
+
+  class << self
+    def call!(...)
+      super
+    rescue ActiveCall::ValidationError => e
+      raise zoho_sign_validation_error(e)
+    rescue ActiveCall::RequestError => e
+      raise zoho_sign_request_error(e)
+    end
+
+    def zoho_sign_validation_error(exception)
+      ZohoSign::ValidationError.new(exception.errors, exception.message)
+    end
+
+    def zoho_sign_request_error(exception)
+      exception_for(exception.response, exception.errors, exception.message)
+    end
+
+    def exception_for(response, errors, message = nil)
+      exception_type = errors.details[:base].first[:error]
+
+      case exception_type
+      when *EXCEPTION_MAPPING.keys
+        EXCEPTION_MAPPING[exception_type].new(response, errors, message)
+      else
+        ZohoSign::RequestError.new(response, errors, message)
+      end
+    end
+  end
+
+  private
+
+  delegate :exception_for, to: :class
+
+  def connection
+    @_connection ||= Faraday.new do |conn|
+      conn.url_prefix = base_url
+      conn.request :authorization, 'Zoho-oauthtoken', -> { access_token }
+      conn.request :multipart
+      conn.request :url_encoded
+      conn.request :retry
+      conn.response :json
+      conn.response :logger, logger, **logger_options do |logger|
+        logger.filter(/(Authorization:).*"(.+)."/i, '\1 [FILTERED]')
+      end
+      conn.adapter Faraday.default_adapter
+    end
+  end
+
+  def logger_options
+    {
+      headers:   log_headers,
+      log_level: log_level,
+      bodies:    log_bodies,
+      formatter: Faraday::Logging::ColorFormatter, prefix: { request: 'ZohoSign', response: 'ZohoSign' }
+    }
+  end
+
+  def access_token
+    access_token = ENV['ZOHO_SIGN_ACCESS_TOKEN'].presence || cache.read(CACHE_KEY[:access_token])
+    return access_token if access_token.present?
+
+    service = ZohoSign::AccessToken::GetService.call
+    cache.fetch(CACHE_KEY[:access_token], expires_in: [service.expires_in - 10, 0].max) { service.facade.access_token }
+  end
+
+  def bad_request?
+    response.status == 400
+  end
+
+  def unauthorized?
+    response.status == 401
+  end
+
+  def forbidden?
+    response.status == 403
+    return false unless response.status == 400 && response.body.key?('code')
+
+    # 4003: Access to view the document is denied.
+    return true if [4003].include?(response.body['code'])
+
+    false
+  end
+
+  def not_found?
+    return true if response.status == 404
+    return false unless response.status == 400 && response.body.key?('code')
+
+    # 4066: Invalid Request ID.
+    # 20405: Invalid Template ID.
+    return true if [4066, 20405].include?(response.body['code'])
+
+    false
+  end
+
+  # TODO: Confirm.
+  def proxy_authentication_required?
+    response.status == 407
+  end
+
+  # TODO: Confirm.
+  def request_timeout?
+    response.status == 408
+  end
+
+  # TODO: Confirm.
+  def conflict?
+    response.status == 409
+  end
+
+  def unprocessable_entity?
+    return true if response.status == 422
+    return false unless response.status == 400 && response.body.key?('code')
+
+    # 4021: Something went wrong. One or more fields contain errors.
+    # 9009: ...
+    # 9043: Extra key found.
+    # 9056: Action array size mismatch from the templates.
+    return true if [4021, 9043, 9009, 9056].include?(response.body['code'])
+
+    false
+  end
+
+  def too_many_requests?
+    return false unless response.status == 400 && response.body.key?('error_description')
+
+    response.body['error_description'].include?('too many requests')
+  end
+end

data/lib/zoho_sign/current_user/facade.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+class ZohoSign::CurrentUser::Facade
+  attr_reader :account_id, :account_type, :api_credits_left, :api_documents_used, :automation_limit,
+    :automation_used_count, :branding, :configurations, :country, :documents_used, :enable_old_viewer_page, :features,
+    :first_name, :iam_photo_url, :is_admin, :is_api_account, :is_cloud_signing_allowed, :is_owner, :is_sign_trial,
+    :is_trial, :is_visible_sign_option_allowed, :is_zoho_one, :language, :last_name, :license_type, :logo_url,
+    :monthly_bulk_used, :monthly_signforms_used, :multiportal_enabled, :no_of_documents, :org_name, :organizations,
+    :payment_url, :photo_url, :plan_edition, :plan_group, :profile, :profile_details, :send_mail_from,
+    :show_api_warning_msg, :smtp_configured, :user_email, :user_id, :visible_sign_settings, :zo_users_url, :zooid,
+    :zuid, :zsoid
+
+  def initialize(hash)
+    @account_id                     = hash['account_id']
+    @account_type                   = hash['account_type']
+    @api_credits_left               = hash['api_credits_left']
+    @api_documents_used             = hash['api_documents_used']
+    @automation_limit               = hash['automation_limit']
+    @automation_used_count          = hash['automation_used_count']
+    @branding                       = hash['branding']
+    @configurations                 = hash['configurations']
+    @country                        = hash['country']
+    @documents_used                 = hash['documents_used']
+    @enable_old_viewer_page         = hash['enable_old_viewer_page']
+    @features                       = hash['features']
+    @first_name                     = hash['first_name']
+    @iam_photo_url                  = hash['IAM_photo_url']
+    @is_admin                       = hash['is_admin']
+    @is_api_account                 = hash['is_api_account']
+    @is_cloud_signing_allowed       = hash['is_cloud_signing_allowed']
+    @is_owner                       = hash['is_owner']
+    @is_sign_trial                  = hash['is_sign_trial']
+    @is_trial                       = hash['is_trial']
+    @is_visible_sign_option_allowed = hash['is_visible_sign_option_allowed']
+    @is_zoho_one                    = hash['is_zoho_one']
+    @language                       = hash['language']
+    @last_name                      = hash['last_name']
+    @license_type                   = hash['license_type']
+    @logo_url                       = hash['logo_url']
+    @monthly_bulk_used              = hash['monthly_bulk_used']
+    @monthly_signforms_used         = hash['monthly_signforms_used']
+    @multiportal_enabled            = hash['multiportal_enabled']
+    @no_of_documents                = hash['no_of_documents']
+    @org_name                       = hash['org_name']
+    @organizations                  = hash['organizations']
+    @payment_url                    = hash['payment_url']
+    @photo_url                      = hash['photo_url']
+    @plan_edition                   = hash['plan_edition']
+    @plan_group                     = hash['plan_group']
+    @profile                        = hash['profile']
+    @profile_details                = hash['profile_details']
+    @send_mail_from                 = hash['send_mail_from']
+    @show_api_warning_msg           = hash['show_api_warning_msg']
+    @smtp_configured                = hash['smtp_configured']
+    @user_email                     = hash['user_email']
+    @user_id                        = hash['user_id']
+    @visible_sign_settings          = hash['visible_sign_settings']
+    @zo_users_url                   = hash['zo_users_url']
+    @zooid                          = hash['zooid']
+    @zuid                           = hash['ZUID']
+    @zsoid                          = hash['ZSOID']
+  end
+end

data/lib/zoho_sign/current_user/get_service.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class ZohoSign::CurrentUser::GetService < ZohoSign::BaseService
+  after_call :set_facade
+
+  delegate_missing_to :@facade
+
+  def initialize; end
+
+  # Get the current user.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoSign::CurrentUser::GetService.call
+  #
+  #   service.success? # => true
+  #   service.errors # => #<ActiveModel::Errors []>
+  #
+  #   service.response # => #<Faraday::Response ...>
+  #   service.response.status # => 200
+  #   service.response.body # => {}
+  #
+  #   service.facade # => #<ZohoSign::CurrentUser::Facade ...>
+  #   service.facade.zsoid
+  #   service.zsoid
+  #
+  # GET /api/v1/currentuser
+  def call
+    connection.get('currentuser')
+  end
+
+  private
+
+  def set_facade
+    @facade = ZohoSign::CurrentUser::Facade.new(response.body['users'])
+  end
+end

data/lib/zoho_sign/document/action/embed_token/facade.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class ZohoSign::Document::Action::EmbedToken::Facade
+  attr_reader :sign_url
+
+  def initialize(hash)
+    @sign_url = hash['sign_url']
+  end
+end

data/lib/zoho_sign/document/action/embed_token/get_service.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+class ZohoSign::Document::Action::EmbedToken::GetService < ZohoSign::BaseService
+  attr_reader :id, :request_id, :host
+
+  after_call :set_facade
+
+  delegate_missing_to :@facade
+
+  validates :id, :request_id, :host, presence: true
+
+  def initialize(id:, request_id:, host:)
+    @id         = id
+    @request_id = request_id
+    @host       = host
+  end
+
+  # Get a document.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoSign::Document::Action::EmbedToken::GetService.call(id: '', request_id: '', host: '')
+  #
+  #   service.success? # => true
+  #   service.errors # => #<ActiveModel::Errors []>
+  #
+  #   service.response # => #<Faraday::Response ...>
+  #   service.response.status # => 200
+  #   service.response.body # => {}
+  #
+  #   service.facade # => #<ZohoSign::Document::Action::EmbedToken::Facade ...>
+  #   service.facade.request_name
+  #   service.request_name
+  #
+  # POST /api/v1/requests/:request_id/actions/:id/embedtoken
+  def call
+    connection.post("/api/v1/requests/#{request_id}/actions/#{id}/embedtoken", **params)
+  end
+
+  private
+
+  def params
+    {
+      host: host
+    }
+  end
+
+  def set_facade
+    @facade = ZohoSign::Document::Action::EmbedToken.new(response.body)
+  end
+end

data/lib/zoho_sign/document/create_service.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+class ZohoSign::Document::CreateService < ZohoSign::BaseService
+  attr_reader :data, :file, :file_content_type, :file_name
+
+  validates :file, :file_content_type, :data, presence: true
+
+  after_call :set_facade
+
+  delegate_missing_to :@facade
+
+  def initialize(data:, file:, file_content_type:, file_name: nil)
+    @file              = file
+    @file_content_type = file_content_type
+    @file_name         = file_name
+    @data              = data
+  end
+
+  # Create a document.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoSign::Document::CreateService.call(
+  #     file: '/path/to/file.pdf', # or File.open('/path/to/file.pdf')
+  #     file_name: 'file.pdf',
+  #     file_content_type: 'application/pdf',
+  #     data: {
+  #       requests: {
+  #         request_name: 'Name',
+  #         is_sequential: false,
+  #         actions: [{
+  #           action_type: 'SIGN',
+  #           recipient_email: 'eric.cartman@example.com',
+  #           recipient_name: 'Eric Cartman',
+  #           verify_recipient: true,
+  #           verification_type: 'EMAIL'
+  #         }]
+  #       }
+  #     }
+  #   )
+  #
+  #   service.success? # => true
+  #   service.errors # => #<ActiveModel::Errors []>
+  #
+  #   service.response # => #<Faraday::Response ...>
+  #   service.response.status # => 200
+  #   service.response.body # => {}
+  #
+  #   service.facade # => #<ZohoSign::Document::Facade ...>
+  #   service.facade.request_name
+  #   service.request_name
+  #
+  # POST /api/v1/requests
+  def call
+    connection.post('requests', **params)
+  end
+
+  private
+
+  def params
+    {
+      file: Faraday::Multipart::FilePart.new(file, file_content_type, file_name),
+      data: data.to_json
+    }
+  end
+
+  def set_facade
+    @facade = ZohoSign::Document::Facade.new(response.body['requests'])
+  end
+end

data/lib/zoho_sign/document/delete_service.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class ZohoSign::Document::DeleteService < ZohoSign::BaseService
+  attr_reader :id
+
+  validates :id, presence: true
+
+  def initialize(id:)
+    @id = id
+  end
+
+  # Delete a document.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoSign::Document::DeleteService.call(id: '')
+  #
+  #   service.success? # => true
+  #   service.errors # => #<ActiveModel::Errors []>
+  #
+  #   service.response # => #<Faraday::Response ...>
+  #   service.response.status # => 200
+  #   service.response.body # => {}
+  #
+  # PUT /api/v1/requests/:id/delete
+  def call
+    connection.put("requests/#{id}/delete")
+  end
+end

data/lib/zoho_sign/document/facade.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class ZohoSign::Document::Facade
+  attr_reader :action_time, :actions, :attachment_size, :attachments, :created_time, :description, :document_fields,
+    :document_ids, :email_reminders, :expire_by, :expiration_days, :folder_id, :folder_name, :in_process, :is_deleted,
+    :is_expiring, :is_sequential, :modified_time, :notes, :owner_email, :owner_first_name, :owner_id, :owner_last_name,
+    :reminder_period, :request_id, :request_name, :request_status, :request_type_id, :request_type_name, :self_sign,
+    :sign_percentage, :sign_submitted_time, :template_ids, :templates_used, :validity, :visible_sign_settings,
+    :zsdocumentid
+
+  def initialize(hash)
+    @action_time           = hash['action_time']
+    @actions               = hash['actions']
+    @attachment_size       = hash['attachment_size']
+    @attachments           = hash['attachments']
+    @created_time          = hash['created_time']
+    @description           = hash['description']
+    @document_fields       = hash['document_fields']
+    @document_ids          = hash['document_ids']
+    @email_reminders       = hash['email_reminders']
+    @expire_by             = hash['expire_by']
+    @expiration_days       = hash['expiration_days']
+    @folder_id             = hash['folder_id']
+    @folder_name           = hash['folder_name']
+    @in_process            = hash['in_process']
+    @is_deleted            = hash['is_deleted']
+    @is_expiring           = hash['is_expiring']
+    @is_sequential         = hash['is_sequential']
+    @modified_time         = hash['modified_time']
+    @notes                 = hash['notes']
+    @owner_email           = hash['owner_email']
+    @owner_first_name      = hash['owner_first_name']
+    @owner_id              = hash['owner_id']
+    @owner_last_name       = hash['owner_last_name']
+    @reminder_period       = hash['reminder_period']
+    @request_id            = hash['request_id']
+    @request_name          = hash['request_name']
+    @request_status        = hash['request_status']
+    @request_type_id       = hash['request_type_id']
+    @request_type_name     = hash['request_type_name']
+    @self_sign             = hash['self_sign']
+    @sign_percentage       = hash['sign_percentage']
+    @sign_submitted_time   = hash['sign_submitted_time']
+    @template_ids          = hash['template_ids']
+    @templates_used        = hash['templates_used']
+    @validity              = hash['validity']
+    @visible_sign_settings = hash['visible_sign_settings']
+    @zsdocumentid          = hash['zsdocumentid']
+  end
+end

data/lib/zoho_sign/document/get_service.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class ZohoSign::Document::GetService < ZohoSign::BaseService
+  attr_reader :id
+
+  after_call :set_facade
+
+  delegate_missing_to :@facade
+
+  validates :id, presence: true
+
+  def initialize(id: nil)
+    @id = id
+  end
+
+  # Get a document.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoSign::Document::GetService.call(id: '')
+  #
+  #   service.success? # => true
+  #   service.errors # => #<ActiveModel::Errors []>
+  #
+  #   service.response # => #<Faraday::Response ...>
+  #   service.response.status # => 200
+  #   service.response.body # => {}
+  #
+  #   service.facade # => #<ZohoSign::Document::Facade ...>
+  #   service.facade.request_name
+  #   service.request_name
+  #
+  # GET /api/v1/requests/:id
+  def call
+    connection.get("requests/#{id}")
+  end
+
+  private
+
+  def set_facade
+    @facade = ZohoSign::Document::Facade.new(response.body['requests'])
+  end
+end

data/lib/zoho_sign/document/list_service.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+class ZohoSign::Document::ListService < ZohoSign::BaseService
+  SORT_COLUMNS = %w[request_name folder_name owner_full_name recipient_email form_name created_time].freeze
+  SORT_ORDERS  = %w[ASC DESC].freeze
+
+  include Enumerable
+
+  attr_reader :limit, :offset, :sort_column, :sort_order, :search_columns
+
+  validates :limit, presence: true, numericality: { greater_than_or_equal_to: 1 }
+  validates :sort_order, inclusion: { in: SORT_ORDERS, message: "Sort order must be one of #{SORT_ORDERS.join(', ')}" }
+
+  validates :sort_column, inclusion: {
+    in:      SORT_COLUMNS,
+    message: "Sort column must be one of #{SORT_COLUMNS.join(', ')}"
+  }
+
+  validate do
+    next if search_columns.empty?
+    next if (SORT_COLUMNS | search_columns.keys.map(&:to_s)).size == SORT_COLUMNS.size
+
+    errors.add(:search_columns, "keys must be one of #{SORT_COLUMNS.join(', ')}")
+    throw :abort
+  end
+
+  def initialize(limit: Float::INFINITY, offset: 1, sort_column: 'created_time', sort_order: 'DESC', search_columns: {})
+    @limit          = limit
+    @offset         = offset
+    @sort_column    = sort_column
+    @sort_order     = sort_order
+    @search_columns = search_columns
+  end
+
+  # List documents.
+  #
+  # ==== Examples
+  #
+  #   service = ZohoSign::Document::ListService.call.first
+  #   service.request_name
+  #
+  #   ZohoSign::Document::ListService.call(offset: 11, limit: 10).each { _1 }
+  #   ZohoSign::Document::ListService.call(sort_column: 'recipient_email', sort_order: 'ASC').each { _1 }
+  #   ZohoSign::Document::ListService.call(search_columns: { recipient_email: 'eric.cartman@example.com' }).each { _1 }
+  #
+  # GET /api/v1/requests
+  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('requests', data: params.to_json)
+        validate(:response)
+
+        unless success?
+          raise exception_for(response, errors) if bang?
+
+          throw :list_end
+        end
+
+        response.body['requests'].each do |hash|
+          yield ZohoSign::Document::Facade.new(hash)
+          total += 1
+          throw :list_end if total >= limit
+        end
+
+        break unless response.body.dig('page_context', 'has_more_rows')
+
+        @_params[:page_context][:start_index] += max_limit_per_request
+      end
+    end
+  end
+
+  private
+
+  def params
+    @_params ||= {
+      page_context: {
+        row_count:      max_limit_per_request,
+        start_index:    offset,
+        search_columns: search_columns,
+        sort_column:    sort_column,
+        sort_order:     sort_order
+      }
+    }
+  end
+
+  def max_limit_per_request
+    @_max_limit_per_request ||= limit.infinite? ? 100 : [limit, 100].min
+  end
+end