active_call-zoho_sign 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d75781aad919dcd23868fbc1e9e4bd86e9d69c923cdbd0142a29c78e44357e48
-  data.tar.gz: dd7e55f14105e2081f6f4b1668231614949e77809e0310cbc525c9fbfd3d79c7
+  metadata.gz: ba562fec7bae27b72ad781e923c0b1db6f0076568a170769ed9490dd0927ca9d
+  data.tar.gz: a2e7dc48e0a7b6cf7774e23a5b93be6026bf7c58b695598a79bd570a5a3e84a0
 SHA512:
-  metadata.gz: a7831f4b4ff12eccab031060e6f5184457181ef1412b7cbd046f18b2bef7bb8cbd772108e97898c3d2b7e9968d8b1985d394d04a1c60ff0f0ee08f4c00986e25
-  data.tar.gz: df1e6eb122cacf3d23be1d9b5cee762ba439eaeae116a9b98a3d2136e05fbd0fafaa5eadbcb9a70ac45ac7e1a9acdfa7335e6dff70454ca75492b0ba5457d9a0
+  metadata.gz: 309cf5cdb4c67fbb25e470000a3a81dd21c19209018ecd8e206a8be79ef396537bd5e835e928a0e39ed454bf92327ad9f44c5e77c07279b71ea752d408245a7f
+  data.tar.gz: ea0fd98f0da44b1c564a7f743187f71e3691cd820d8485700e6f21502bc5c9d308d9dcfe68e1e8ed0f2b75a27bffb3b7cafdeb7cfc7530389e656cb4d9105bfc

data/.rubocop.yml

@@ -20,7 +20,8 @@ Layout/HashAlignment:
   EnforcedColonStyle: table
 
 Layout/LineLength:
-  AllowedPatterns: ['initialize']
+  AllowedPatterns:
+    - initialize
 
 Lint/MissingSuper:
   Enabled: false
@@ -37,8 +38,7 @@ Metrics/ClassLength:
 
 Metrics/CyclomaticComplexity:
   Exclude:
-    - lib/zoho_sign/document/list_service.rb
-    - lib/zoho_sign/template/list_service.rb
+    - lib/zoho_sign/concerns/enumerable.rb
 
 Metrics/MethodLength:
   Enabled: false

data/CHANGELOG.md

@@ -1,4 +1,10 @@
-## [Unreleased]
+## [0.1.5] - 2025-04-03
+
+- Refactor list endpoints to use `ZohoSign::Enumerable`.
+
+## [0.1.4] - 2025-03-31
+
+- Sign a document embedded link fix.
 
 ## [0.1.3] - 2025-03-25
 

data/README.md

@@ -4,6 +4,20 @@
 
 Zoho Sign exposes the [Zoho Sign API](https://www.zoho.com/sign/api) endpoints through service objects.
 
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [Using call](#using-call)
+  - [Using call!](#using-call!)
+  - [When to use call or call!](#using-call-or-call!)
+  - [Using lists](#using-lists)
+  - [Documents](#documents)
+  - [Folders](#folders)
+  - [Templates](#templates)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -45,7 +59,7 @@ While testing, you can set your temporary development OAuth access token in the
 
 ## Usage
 
-### Using `.call`
+### <a name='using-call'></a>Using `call`
 
 Each service object returned will undergo validation before the `call` method is invoked to access API endpoints.
 
@@ -99,7 +113,7 @@ service.response.status # => 400
 service.response.body # => {"code"=>9004, "message"=>"No match found", "status"=>"failure"}
 ```
 
-### Using `.call!`
+### <a name='using-call!'></a>Using `call!`
 
 Each service object returned will undergo validation before the `call!` method is invoked to access API endpoints.
 
@@ -154,14 +168,14 @@ rescue ZohoSign::RequestError => exception
   exception.response.body # => {"code"=>9004, "message"=>"No match found", "status"=>"failure"}
 ```
 
-### When to use `.call` or `.call!`
+### <a name='using-call-or-call!'></a>When to use `call` or `call!`
 
-An example of where to use `.call` would be in a **controller** doing an inline synchronous request.
+An example of where to use `call` would be in a **controller** doing an inline synchronous request.
 
 ```ruby
 class DocumentController < ApplicationController
   def update
-    @document = ZohoSign::Document::UpdateService.call(params)
+    @document = ZohoSign::Document::UpdateService.call(**params)
 
     if @document.success?
       redirect_to [@document], notice: 'Success', status: :see_other
@@ -173,7 +187,7 @@ class DocumentController < ApplicationController
 end
 ```
 
-An example of where to use `.call!` would be in a **job** doing an asynchronous request.
+An example of where to use `call!` would be in a **job** doing an asynchronous request.
 
 You can use the exceptions to determine which retry strategy to use and which to discard.
 
@@ -185,19 +199,20 @@ class DocumentJob < ApplicationJob
   retry_on ZohoSign::TooManyRequestsError, wait: :polynomially_longer, attempts: 10
 
   def perform
-    ZohoSign::Document::UpdateService.call!(params)
+    ZohoSign::Document::UpdateService.call!(**params)
   end
 end
 ```
 
-### Documents
+### Using lists
+
+If you don't provide the `limit` argument, multiple API requests will be made untill all records have been returned. You could be rate limited, so use wisely.
 
-#### List documents.
+Note that the `offset` argument starts at `1` for the first item.
 
-Note that the `offset` starts at `1` for the first item.
+### Documents
 
-If you don't provide a `limit`, multiple API requests will be made untill all records have been returned. You could be
-rate limited, so use wisely.
+#### List documents
 
 ```ruby
 service = ZohoSign::Document::ListService.call(offset: 1, limit: 10).each do |facade|
@@ -217,10 +232,9 @@ Filter by column.
 ZohoSign::Document::ListService.call(search_columns: { recipient_email: 'eric.cartman@example.com' }).map { _1 }
 ```
 
-Columns to sort and filter by are `request_name`, `folder_name`, `owner_full_name`, `recipient_email`,
-`form_name` `created_time`.
+Columns to sort and filter by are `request_name`, `folder_name`, `owner_full_name`, `recipient_email`, `form_name` and `created_time`.
 
-#### Get a document.
+#### Get a document
 
 ```ruby
 service = ZohoSign::Document::GetService.call(id: '')
@@ -235,7 +249,7 @@ service.sign_percentage
 ...
 ```
 
-#### Create a document.
+#### Create a document
 
 ```ruby
 service = ZohoSign::Document::CreateService.call(
@@ -258,7 +272,7 @@ service = ZohoSign::Document::CreateService.call(
 )
 ```
 
-#### Update a document.
+#### Update a document
 
 ```ruby
 service = ZohoSign::Document::UpdateService.call(
@@ -277,12 +291,21 @@ service = ZohoSign::Document::UpdateService.call(
 )
 ```
 
-#### Delete a document.
+#### Delete a document
 
 ```ruby
 service = ZohoSign::Document::DeleteService.call(id: '')
 ```
 
+#### Sign a document
+
+A unique signing URL will be generated, which will be valid for two minutes. If the signing page is not open by then, a new link needs to be generated and it is a one-time usable URL.
+
+```ruby
+service = ZohoSign::Document::Action::EmbedToken::GetService.call(request_id: '', action_id: '', host: '')
+service.sign_url
+```
+
 ### Folders
 
 TODO: ...
@@ -297,12 +320,7 @@ TODO: ...
 
 ### Templates
 
-#### List templates.
-
-Note that the `offset` starts at `1` for the first item.
-
-If you don't provide a `limit`, multiple API requests will be made untill all records have been returned. You could be
-rate limited, so use wisely.
+#### List templates
 
 ```ruby
 service = ZohoSign::Template::ListService.call(offset: 1, limit: 10).each do |facade|
@@ -322,9 +340,9 @@ Filter by column.
 ZohoSign::Template::ListService.call(search_columns: { template_name: 'Eric Template' }).map { _1 }
 ```
 
-Columns to sort and filter by are `template_name`, `owner_first_name`, `modified_time`.
+Columns to sort and filter by are `template_name`, `owner_first_name` and `modified_time`.
 
-#### Get a template.
+#### Get a template
 
 ```ruby
 service = ZohoSign::Template::GetService.call(id: '')
@@ -339,19 +357,19 @@ service.template_name
 ...
 ```
 
-#### Create a template.
+#### Create a template
 
 TODO: ...
 
-#### Update a template.
+#### Update a template
 
 TODO: ...
 
-#### Delete a template.
+#### Delete a template
 
 TODO: ...
 
-#### Create document from template.
+#### Create document from template
 
 The auto filled fields specified in the `field_data` object should be marked as **Prefill by you** when creating the document template.
 

data/lib/zoho_sign/concerns/enumerable.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ZohoSign::Enumerable
+  extend ActiveSupport::Concern
+
+  included do
+    include Enumerable
+
+    attr_reader :path, :list_key, :facade_klass, :limit, :offset
+
+    validates :path, :list_key, :facade_klass, presence: true
+    validates :limit, presence: true, numericality: { greater_than_or_equal_to: 1 }
+  end
+
+  def initialize(path:, list_key:, facade_klass:, limit: Float::INFINITY, offset: 1)
+    @path         = path
+    @list_key     = list_key
+    @facade_klass = facade_klass
+    @limit        = limit
+    @offset       = offset
+  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, data: params.to_json)
+        validate(:response)
+
+        unless success?
+          raise exception_for(response, errors) if bang?
+
+          throw :list_end
+        end
+
+        response.body[list_key].each do |hash|
+          yield facade_klass.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
+      }
+    }
+  end
+
+  def max_limit_per_request
+    @_max_limit_per_request ||= limit.infinite? ? 100 : [limit, 100].min
+  end
+end

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

@@ -1,25 +1,28 @@
 # frozen_string_literal: true
 
 class ZohoSign::Document::Action::EmbedToken::GetService < ZohoSign::BaseService
-  attr_reader :id, :request_id, :host
+  attr_reader :request_id, :action_id, :host
+
+  validates :request_id, :action_id, :host, presence: true
 
   after_call :set_facade
 
   delegate_missing_to :@facade
 
-  validates :id, :request_id, :host, presence: true
-
-  def initialize(id:, request_id:, host:)
-    @id         = id
+  def initialize(request_id:, action_id:, host:)
     @request_id = request_id
+    @action_id  = action_id
     @host       = host
   end
 
-  # Get a document.
+  # Get a signing URL.
+  #
+  # A unique signing URL will be generated, which will be valid for two minutes. If the signing page is not open by
+  # then, a new link needs to be generated and it is a one-time usable URL.
   #
   # ==== Examples
   #
-  #   service = ZohoSign::Document::Action::EmbedToken::GetService.call(id: '', request_id: '', host: '')
+  #   service = ZohoSign::Document::Action::EmbedToken::GetService.call(request_id: '', action_id: '', host: '')
   #
   #   service.success? # => true
   #   service.errors # => #<ActiveModel::Errors []>
@@ -29,12 +32,12 @@ class ZohoSign::Document::Action::EmbedToken::GetService < ZohoSign::BaseService
   #   service.response.body # => {}
   #
   #   service.facade # => #<ZohoSign::Document::Action::EmbedToken::Facade ...>
-  #   service.facade.request_name
-  #   service.request_name
+  #   service.facade.sign_url
+  #   service.sign_url
   #
-  # POST /api/v1/requests/:request_id/actions/:id/embedtoken
+  # POST /api/v1/requests/:request_id/actions/:action_id/embedtoken
   def call
-    connection.post("/api/v1/requests/#{request_id}/actions/#{id}/embedtoken", **params)
+    connection.post("/api/v1/requests/#{request_id}/actions/#{action_id}/embedtoken", **params)
   end
 
   private
@@ -46,6 +49,6 @@ class ZohoSign::Document::Action::EmbedToken::GetService < ZohoSign::BaseService
   end
 
   def set_facade
-    @facade = ZohoSign::Document::Action::EmbedToken.new(response.body)
+    @facade = ZohoSign::Document::Action::EmbedToken::Facade.new(response.body)
   end
 end

data/lib/zoho_sign/document/get_service.rb

@@ -9,7 +9,7 @@ class ZohoSign::Document::GetService < ZohoSign::BaseService
 
   validates :id, presence: true
 
-  def initialize(id: nil)
+  def initialize(id:)
     @id = id
   end
 

data/lib/zoho_sign/document/list_service.rb

@@ -4,11 +4,10 @@ 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
+  include ZohoSign::Enumerable
 
-  attr_reader :limit, :offset, :sort_column, :sort_order, :search_columns
+  attr_reader :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: {
@@ -24,14 +23,6 @@ class ZohoSign::Document::ListService < ZohoSign::BaseService
     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
@@ -39,43 +30,35 @@ class ZohoSign::Document::ListService < ZohoSign::BaseService
   #   service = ZohoSign::Document::ListService.call.first
   #   service.request_name
   #
+  # If you don't provide the `limit` argument, multiple API requests will be made untill all records have been returned.
+  # You could be rate limited, so use wisely.
+  #
   #   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 }
+  #
+  # Sort by column.
+  #
+  #   ZohoSign::Document::ListService.call(sort_column: 'recipient_email', sort_order: 'ASC').map { _1 }
+  #
+  # Filter by column.
+  #
+  #   ZohoSign::Document::ListService.call(search_columns: { recipient_email: 'eric.cartman@example.com' }).map { _1 }
+  #
+  # Columns to sort and filter by are `request_name`, `folder_name`, `owner_full_name`, `recipient_email`, `form_name`
+  # and `created_time`.
   #
   # 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')
+  def initialize(limit: Float::INFINITY, offset: 1, sort_column: 'created_time', sort_order: 'DESC', search_columns: {})
+    @sort_column    = sort_column
+    @sort_order     = sort_order
+    @search_columns = search_columns
 
-        @_params[:page_context][:start_index] += max_limit_per_request
-      end
-    end
+    super(
+      path:         'requests',
+      list_key:     'requests',
+      facade_klass: ZohoSign::Document::Facade,
+      limit:        limit,
+      offset:       offset
+    )
   end
 
   private
@@ -91,8 +74,4 @@ class ZohoSign::Document::ListService < ZohoSign::BaseService
       }
     }
   end
-
-  def max_limit_per_request
-    @_max_limit_per_request ||= limit.infinite? ? 100 : [limit, 100].min
-  end
 end

data/lib/zoho_sign/template/get_service.rb

@@ -9,7 +9,7 @@ class ZohoSign::Template::GetService < ZohoSign::BaseService
 
   validates :id, presence: true
 
-  def initialize(id: nil)
+  def initialize(id:)
     @id = id
   end
 

data/lib/zoho_sign/template/list_service.rb

@@ -4,11 +4,10 @@ class ZohoSign::Template::ListService < ZohoSign::BaseService
   SORT_COLUMNS = %w[template_name owner_first_name modified_time].freeze
   SORT_ORDERS  = %w[ASC DESC].freeze
 
-  include Enumerable
+  include ZohoSign::Enumerable
 
-  attr_reader :limit, :offset, :sort_column, :sort_order, :search_columns
+  attr_reader :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: {
@@ -24,14 +23,6 @@ class ZohoSign::Template::ListService < ZohoSign::BaseService
     throw :abort
   end
 
-  def initialize(limit: Float::INFINITY, offset: 1, sort_column: 'template_name', 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
@@ -39,43 +30,34 @@ class ZohoSign::Template::ListService < ZohoSign::BaseService
   #   service = ZohoSign::Template::ListService.call.first
   #   service.request_name
   #
+  # If you don't provide the `limit` argument, multiple API requests will be made untill all records have been returned.
+  # You could be rate limited, so use wisely.
+  #
   #   ZohoSign::Template::ListService.call(offset: 11, limit: 10).each { _1 }
-  #   ZohoSign::Template::ListService.call(sort_column: 'template_name', sort_order: 'ASC').each { _1 }
-  #   ZohoSign::Template::ListService.call(search_columns: { template_name: 'Eric Template' }).each { _1 }
+  #
+  # Sort by column.
+  #
+  #   ZohoSign::Template::ListService.call(sort_column: 'template_name', sort_order: 'ASC').map { _1 }
+  #
+  # Filter by column.
+  #
+  #   ZohoSign::Template::ListService.call(search_columns: { template_name: 'Eric Template' }).map { _1 }
+  #
+  # Columns to sort and filter by are `template_name`, `owner_first_name` and `modified_time`.
   #
   # GET /api/v1/templates
-  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('templates', data: params.to_json)
-        validate(:response)
-
-        unless success?
-          raise exception_for(response, errors) if bang?
-
-          throw :list_end
-        end
-
-        response.body['templates'].each do |hash|
-          yield ZohoSign::Template::Facade.new(hash)
-          total += 1
-          throw :list_end if total >= limit
-        end
-
-        break unless response.body.dig('page_context', 'has_more_rows')
+  def initialize(limit: Float::INFINITY, offset: 1, sort_column: 'template_name', sort_order: 'DESC', search_columns: {})
+    @sort_column    = sort_column
+    @sort_order     = sort_order
+    @search_columns = search_columns
 
-        @_params[:page_context][:start_index] += max_limit_per_request
-      end
-    end
+    super(
+      path:         'templates',
+      list_key:     'templates',
+      facade_klass: ZohoSign::Template::Facade,
+      limit:        limit,
+      offset:       offset
+    )
   end
 
   private
@@ -91,8 +73,4 @@ class ZohoSign::Template::ListService < ZohoSign::BaseService
       }
     }
   end
-
-  def max_limit_per_request
-    @_max_limit_per_request ||= limit.infinite? ? 100 : [limit, 100].min
-  end
 end

data/lib/zoho_sign/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZohoSign
-  VERSION = '0.1.3'
+  VERSION = '0.1.5'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_call-zoho_sign
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Kobus Joubert
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-25 00:00:00.000000000 Z
+date: 2025-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_call
@@ -112,6 +112,7 @@ files:
 - lib/zoho_sign/access_token/facade.rb
 - lib/zoho_sign/access_token/get_service.rb
 - lib/zoho_sign/base_service.rb
+- lib/zoho_sign/concerns/enumerable.rb
 - lib/zoho_sign/current_user/facade.rb
 - lib/zoho_sign/current_user/get_service.rb
 - lib/zoho_sign/document/action/embed_token/facade.rb