clicksign-ruby-sdk 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2fa45c00d6994b4009e9888eb982da569f1657c692b7e83a5db76c69067ebc2
-  data.tar.gz: e74c86dab5a02752fd9bb3a388cf54c78ae90e9a376cdac163bf5dca090fd5e9
+  metadata.gz: a45728b201a9703e1d70cb6de98056f85da9a524d9d0c122a1ed951d6f98ef5b
+  data.tar.gz: 7a2aea99029254b4849b27090f40927d4cbf66d44cb516f121ea14c65544f141
 SHA512:
-  metadata.gz: 86b4b41f6607d89ea58786225502c699902523d05ff72f60d983449fc9a318d794ab1c164ce1d475a073ea868d22ee65da53f7e36c61cb477e28e4cea7fa86f4
-  data.tar.gz: 484d16275cda5bf7e85413dcc3383776988574de052d6715a7d08e591d54701b13e3dd52a69c9a000977f8d51cc07a7590968050c6456b35cec48c914086a737
+  metadata.gz: e9cb3bdaff221f8a8e58a9ef4ca47363962e19b7dcb4f22eb129cb1f5f3b60812550db76301ee8a36473be11490293932895d83c91ef60d10928206d090cd162
+  data.tar.gz: 8c3cd41e15ba5c21136fc3ee4b53fcb96c231620735c17401acbd046a032262b31a9a1617f07ec704e9a9593dedb8023dd82019afe156cee782356c78c297199

data/README.md

@@ -95,6 +95,8 @@ A API usa o header `Authorization: <seu-token>` **sem** o prefixo `Bearer`.
 
 > **Segurança:** não commite tokens no código. Use variáveis de ambiente ou cofre de secrets (Rails credentials, etc.).
 
+> **`api_key` é obrigatório em runtime:** o SDK não valida a presença do token no boot. Se `api_key` for `nil`, nenhum erro é levantado no `configure` — o `AuthenticationError` só aparece na primeira request HTTP. Use `ENV.fetch('CLICKSIGN_API_KEY')` (em vez de `ENV[]`) para detectar a ausência da variável no startup da aplicação.
+
 > **Multi-conta / multi-tenant:** se cada requisição pode usar credenciais diferentes (SaaS, workers por cliente), prefira [`Clicksign::Services`](#multi-conta-e-cliente-instantiável) em vez da config global.
 
 Para testar interativamente no console da gem:
@@ -188,7 +190,7 @@ Com `max_retries > 0`, o client reexecuta a requisição em erros **transitório
 - `Clicksign::RateLimitError`
 - `Clicksign::ServerError` (5xx)
 
-Backoff exponencial com **full jitter** (espera aleatória entre `0` e o teto da tentativa: `0,5s`, `1s`, `2s`… até **30s**), para evitar thundering herd quando muitos clientes falham ao mesmo tempo. Após esgotar as retentativas, a exceção original é relançada.
+Backoff exponencial com **full jitter**: espera aleatória uniforme em `[0, teto)` onde o teto cresce como `0.5s × 2^(tentativa-1)` (0,5s → 1s → 2s…) com cap de **30s**. O zero é possível — o jitter distribui a espera para evitar thundering herd. Após esgotar as retentativas, a exceção original é relançada.
 
 ```ruby
 Clicksign.configure do |c|
@@ -462,12 +464,33 @@ Envelope.list_events(envelope.id)
 # Eventos de um documento
 Document.list_events(document.id, envelope_id: envelope.id)
 
-# Criar evento customizado no documento
-Event.create_for_document(
+# Criar evento de imagem no documento (comprovante JPEG)
+Event.create_add_image(
+  envelope_id: envelope.id,
+  document_id: document.id,
+  title: 'Comprovante de identidade',
+  occurred_at: Time.now.iso8601,
+  content_base64: 'data:image/jpeg;base64,...'
+)
+
+# Criar evento customizado — token_email ou token_sms
+Event.create_custom(
+  envelope_id: envelope.id,
+  document_id: document.id,
+  kind: 'token_email',           # ou 'token_sms'
+  occurred_at: Time.now.iso8601,
+  signer_name: 'Maria Silva',
+  signer_email: 'maria@empresa.com',
+  # signer_phone_number: '11988887777'  # obrigatório quando kind: 'token_sms'
+)
+
+# API de baixo nível — qualquer name customizado
+Event.create(
   envelope_id: envelope.id,
   document_id: document.id,
   name: 'custom',
-  data: { description: 'Etapa interna concluída' }
+  data: { kind: 'token_email', signer_name: 'Maria Silva',
+          signer_email: 'maria@empresa.com', occurred_at: Time.now.iso8601 }
 )
 ```
 

data/lib/clicksign/client.rb

@@ -14,7 +14,7 @@ module Clicksign
     }.freeze
 
     def initialize(api_key:, base_url:, open_timeout: 2, read_timeout: 10,
-                   write_timeout: 10, max_retries: 0)
+      write_timeout: 10, max_retries: 0)
       @api_key       = api_key
       @base_url      = base_url
       @open_timeout  = open_timeout
@@ -88,11 +88,11 @@ module Clicksign
 
     def http_request(request, uri)
       Net::HTTP.start(uri.host, uri.port,
-                      use_ssl: uri.scheme == 'https',
-                      open_timeout: @open_timeout,
-                      read_timeout: @read_timeout,
-                      write_timeout: @write_timeout,
-                      &proc { |http| http.request(request) })
+        use_ssl: uri.scheme == 'https',
+        open_timeout: @open_timeout,
+        read_timeout: @read_timeout,
+        write_timeout: @write_timeout,
+        &proc { |http| http.request(request) })
     end
 
     def handle_response(response, context, start)

data/lib/clicksign/configuration.rb

@@ -8,7 +8,7 @@ module Clicksign
     }.freeze
 
     attr_accessor :api_key, :base_url, :open_timeout, :read_timeout,
-                  :write_timeout, :max_retries, :logger
+      :write_timeout, :max_retries, :logger
 
     def initialize
       @base_url      = 'https://app.clicksign.com/api/v3'
@@ -21,7 +21,7 @@ module Clicksign
     def environment=(env)
       url = ENVIRONMENTS.fetch(env.to_sym) do
         raise ArgumentError,
-              "Unknown environment: #{env}. Valid: #{ENVIRONMENTS.keys.join(', ')}"
+          "Unknown environment: #{env}. Valid: #{ENVIRONMENTS.keys.join(', ')}"
       end
       self.base_url = url
     end

data/lib/clicksign/error_handler.rb

@@ -50,7 +50,8 @@ module Clicksign
       errors = body['errors']
       return response.message unless errors.is_a?(Array)
 
-      errors.filter_map { |e| e['detail'] || e['title'] }.join(', ')
+      result = errors.filter_map { |e| e['detail'] || e['title'] }.join(', ')
+      result.empty? ? response.message : result
     end
   end
 end

data/lib/clicksign/errors.rb

@@ -5,7 +5,7 @@ module Clicksign
     attr_reader :status_code, :request_id, :response_body, :response_headers
 
     def initialize(message = nil, status_code: nil, request_id: nil,
-                   response_body: nil, response_headers: {})
+      response_body: nil, response_headers: {})
       super(message)
       @status_code      = status_code
       @request_id       = request_id

data/lib/clicksign/instrumentation.rb

@@ -5,6 +5,7 @@ module Clicksign
     EVENTS = %i[request retry error].freeze
 
     @callbacks = Hash.new { |h, k| h[k] = [] }
+    @mutex     = Mutex.new
 
     class << self
       def on(event, &block)
@@ -12,11 +13,12 @@ module Clicksign
           raise ArgumentError, "Unknown event: #{event}. Valid: #{EVENTS.join(', ')}"
         end
 
-        @callbacks[event] << block
+        @mutex.synchronize { @callbacks[event] << block }
       end
 
       def publish(event, payload)
-        @callbacks[event].each do |cb|
+        callbacks = @mutex.synchronize { @callbacks[event].dup }
+        callbacks.each do |cb|
           cb.call(payload)
         rescue StandardError => e
           Clicksign.configuration.logger&.warn(
@@ -28,7 +30,7 @@ module Clicksign
 
       # Removes all registered callbacks — intended for test teardown.
       def clear
-        @callbacks = Hash.new { |h, k| h[k] = [] }
+        @mutex.synchronize { @callbacks = Hash.new { |h, k| h[k] = [] } }
       end
     end
   end

data/lib/clicksign/json_api/bulk_operations_client.rb

@@ -15,7 +15,7 @@ module Clicksign
       }.freeze
 
       def initialize(api_key:, base_url:, open_timeout: 2, read_timeout: 10,
-                     write_timeout: 10, max_retries: 0)
+        write_timeout: 10, max_retries: 0)
         @api_key       = api_key
         @base_url      = base_url
         @open_timeout  = open_timeout
@@ -78,11 +78,11 @@ module Clicksign
 
       def http_post(request, uri)
         Net::HTTP.start(uri.host, uri.port,
-                        use_ssl: uri.scheme == 'https',
-                        open_timeout: @open_timeout,
-                        read_timeout: @read_timeout,
-                        write_timeout: @write_timeout,
-                        &proc { |http| http.request(request) })
+          use_ssl: uri.scheme == 'https',
+          open_timeout: @open_timeout,
+          read_timeout: @read_timeout,
+          write_timeout: @write_timeout,
+          &proc { |http| http.request(request) })
       end
 
       def headers
@@ -97,8 +97,8 @@ module Clicksign
         return nil if response.body.nil? || response.body.empty?
 
         JSON.parse(response.body)
-      rescue JSON::ParserError
-        nil
+      rescue JSON::ParserError => e
+        raise Error, "Invalid JSON response from bulk operations endpoint: #{e.message}"
       end
     end
   end

data/lib/clicksign/json_api/operations/bulk_requirement.rb

@@ -33,7 +33,7 @@ module Clicksign
         end
 
         def add_rubricate(signer_id:, document_id:, pages: nil, rubric_field: nil,
-                          kind: nil)
+          kind: nil)
           validate_ids!(signer_id, document_id)
           if pages.nil? && rubric_field.nil?
             raise ArgumentError, 'pages or rubric_field is required'

data/lib/clicksign/json_api/query_builder.rb

@@ -13,7 +13,8 @@ module Clicksign
       end
 
       def include(*types)
-        @params['include'] = types.join(',')
+        existing = @params['include']&.split(',') || []
+        @params['include'] = (existing + types.map(&:to_s)).uniq.join(',')
         self
       end
 

data/lib/clicksign/request_instrumentation.rb

@@ -27,13 +27,13 @@ module Clicksign
 
     def publish_retry(request, uri, attempt, error, delay)
       Instrumentation.publish(:retry, {
-                                method: request.method.downcase.to_sym,
-                                path: resource_path(uri),
-                                attempt: attempt,
-                                max_retries: @max_retries,
-                                error: error,
-                                wait_ms: (delay * 1000).round,
-                              })
+        method: request.method.downcase.to_sym,
+        path: resource_path(uri),
+        attempt: attempt,
+        max_retries: @max_retries,
+        error: error,
+        wait_ms: (delay * 1000).round,
+      })
     end
 
     def handle_network_error(error, context, start)

data/lib/clicksign/resource.rb

@@ -133,8 +133,8 @@ module Clicksign
         modules, jsonapi = types.partition { |t| t.is_a?(Module) }
         if modules.any? && jsonapi.any?
           raise ArgumentError,
-                'cannot mix Module with JSON:API ' \
-                'include types — use with_includes for sideload'
+            'cannot mix Module with JSON:API ' \
+            'include types — use with_includes for sideload'
         end
         if modules.any?
           modules.each { |mod| super(mod) }
@@ -193,8 +193,8 @@ module Clicksign
         return if invalid.empty?
 
         raise ArgumentError,
-              'JSON:API include types must be String or Symbol, ' \
-              "got: #{invalid.map(&:class).uniq.join(', ')}"
+          'JSON:API include types must be String or Symbol, ' \
+          "got: #{invalid.map(&:class).uniq.join(', ')}"
       end
 
       private
@@ -212,8 +212,8 @@ module Clicksign
 
         loop do
           raw    = client.get(endpoint,
-                              params: base.merge('page[number]' => page,
-                                                 'page[size]' => per))
+            params: base.merge('page[number]' => page,
+              'page[size]' => per))
           parsed = JsonApi::Parser.parse(raw)
           items  = parsed[:data].map { |item| build_instance(item) }
           yield items
@@ -236,6 +236,8 @@ module Clicksign
       end
 
       def build_instance(data, parent_id: nil)
+        raise NotFoundError, 'API returned null data' if data.nil?
+
         instance = allocate
         instance.send(:load_data, data, parent_id: parent_id)
         instance
@@ -261,7 +263,10 @@ module Clicksign
         ),
       )
       parsed = JsonApi::Parser.parse(raw)
-      load_data(parsed[:data].first, parent_id: @_parent_id)
+      data   = parsed[:data].first
+      raise NotFoundError, 'API returned null data' if data.nil?
+
+      load_data(data, parent_id: @_parent_id)
       self
     end
 
@@ -273,7 +278,10 @@ module Clicksign
     def reload
       raw    = self.class.client.get("#{base_path}/#{@id}")
       parsed = JsonApi::Parser.parse(raw)
-      load_data(parsed[:data].first, parent_id: @_parent_id)
+      data   = parsed[:data].first
+      raise NotFoundError, 'API returned null data' if data.nil?
+
+      load_data(data, parent_id: @_parent_id)
       self
     end
 

data/lib/clicksign/resources/notarial/envelope.rb

@@ -27,23 +27,23 @@ module Clicksign
 
         def self.list_events(envelope_id, **filters)
           nested_list(envelope_id, nested_type: 'events', as: Event,
-                                   params: filter_params(**filters))
+            params: filter_params(**filters))
         end
 
         def self.list_documents(envelope_id, **filters)
           nested_list(envelope_id, nested_type: 'documents', as: Document,
-                                   params: filter_params(**filters))
+            params: filter_params(**filters))
         end
 
         def self.list_signers(envelope_id, **filters)
           nested_list(envelope_id, nested_type: 'signers', as: Signer,
-                                   params: filter_params(**filters))
+            params: filter_params(**filters))
         end
 
         def self.list_signature_watchers(envelope_id, **filters)
           nested_list(envelope_id, nested_type: 'signature_watchers',
-                                   as: SignatureWatcher,
-                                   params: filter_params(**filters))
+            as: SignatureWatcher,
+            params: filter_params(**filters))
         end
 
         def self.list_requirements(envelope_id, **filters)

data/lib/clicksign/resources/notarial/event.rb

@@ -6,7 +6,9 @@ module Clicksign
       class Event < Clicksign::Resource
         self.resource_type = 'events'
 
-        def self.create_for_document(envelope_id:, document_id:, **attributes)
+        CUSTOM_KINDS = %w[token_email token_sms].freeze
+
+        def self.create(envelope_id:, document_id:, **attributes)
           raw = client.post(
             "/envelopes/#{envelope_id}/documents/#{document_id}/events",
             body: JsonApi::Serializer.dump(type: resource_type, attributes: attributes),
@@ -14,6 +16,50 @@ module Clicksign
           parsed = JsonApi::Parser.parse(raw)
           build_instance(parsed[:data].first)
         end
+
+        def self.create_add_image(envelope_id:, document_id:, title:, occurred_at:,
+          content_base64:)
+          create(
+            envelope_id: envelope_id,
+            document_id: document_id,
+            name: 'add_image',
+            content_base64: content_base64,
+            data: { title: title, occurred_at: occurred_at },
+          )
+        end
+
+        def self.create_custom(envelope_id:, document_id:, kind:, occurred_at:,
+          signer_name:, signer_email: nil, signer_phone_number: nil)
+          unless CUSTOM_KINDS.include?(kind.to_s)
+            raise ArgumentError, "kind must be one of: #{CUSTOM_KINDS.join(', ')}"
+          end
+
+          create(
+            envelope_id: envelope_id,
+            document_id: document_id,
+            name: 'custom',
+            data: {
+              kind: kind,
+              occurred_at: occurred_at,
+              signer_name: signer_name,
+              signer_email: signer_email,
+              signer_phone_number: signer_phone_number,
+            }.compact,
+          )
+        end
+
+        # API only exposes GET (list) and POST (create) for events — no singleton routes.
+        def update(**)
+          raise NotImplementedError, 'Event does not support update'
+        end
+
+        def delete
+          raise NotImplementedError, 'Event does not support delete'
+        end
+
+        def reload
+          raise NotImplementedError, 'Event does not support reload'
+        end
       end
     end
   end

data/lib/clicksign/resources/notarial/signature_watcher.rb

@@ -27,7 +27,7 @@ module Clicksign
 
         def update(**)
           raise NotImplementedError,
-                'SignatureWatcher does not support update (route: except: [:update])'
+            'SignatureWatcher does not support update (route: except: [:update])'
         end
 
         def envelope_id

data/lib/clicksign/resources/notarial/signer.rb

@@ -40,7 +40,7 @@ module Clicksign
 
         def update(**)
           raise NotImplementedError,
-                'Signer does not support update (route: except: [:update])'
+            'Signer does not support update (route: except: [:update])'
         end
 
         def base_path

data/lib/clicksign/services.rb

@@ -3,7 +3,7 @@
 module Clicksign
   class Services
     def initialize(api_key:, environment: :production, base_url: nil,
-                   open_timeout: 2, read_timeout: 10, write_timeout: 10, max_retries: 0)
+      open_timeout: 2, read_timeout: 10, write_timeout: 10, max_retries: 0)
       resolved_url = base_url || resolve_environment(environment)
       @client = Client.new(
         api_key: api_key,

data/lib/clicksign/webhook.rb

@@ -30,8 +30,10 @@ module Clicksign
 
     # Constant-time comparison to prevent timing attacks.
     def self.secure_compare?(expected, actual)
+      return false if actual.nil? || actual.to_s.empty?
+
       digest_a = OpenSSL::Digest::SHA256.hexdigest(expected)
-      digest_b = OpenSSL::Digest::SHA256.hexdigest(actual)
+      digest_b = OpenSSL::Digest::SHA256.hexdigest(actual.to_s)
       result = 0
       digest_a.bytes.zip(digest_b.bytes) { |x, y| result |= x ^ y }
       result.zero?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clicksign-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Clicksign
@@ -77,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby SDK for the Clicksign API
 test_files: []