clicksign-ruby-sdk 0.1.5 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a45728b201a9703e1d70cb6de98056f85da9a524d9d0c122a1ed951d6f98ef5b
-  data.tar.gz: 7a2aea99029254b4849b27090f40927d4cbf66d44cb516f121ea14c65544f141
+  metadata.gz: a8730a44f32966cd0d6978150f4c5c5e821de5c168b94f4e69ced112cef211cc
+  data.tar.gz: afe6780086fe195e7559470d86674d83b8927c725e96213f1bb930a43808af54
 SHA512:
-  metadata.gz: e9cb3bdaff221f8a8e58a9ef4ca47363962e19b7dcb4f22eb129cb1f5f3b60812550db76301ee8a36473be11490293932895d83c91ef60d10928206d090cd162
-  data.tar.gz: 8c3cd41e15ba5c21136fc3ee4b53fcb96c231620735c17401acbd046a032262b31a9a1617f07ec704e9a9593dedb8023dd82019afe156cee782356c78c297199
+  metadata.gz: c939a985f4caf49b47d15b2b6637550e20083cf217f077bf0d50c042946b693db885bb8ccad98abc1bfb48a7465d5ebc8ed9c47eef4aac8f32a078c9560fcb12
+  data.tar.gz: 80ee966ee546d6b401c7e427afa7bd7b881b64fb342e18e068469bb24f8b043220b1edc3d853bb3b348e1fac95c4e68284bf14a8a8ef1ac4325b25d176ce7f84

data/README.md

@@ -9,7 +9,7 @@ Cliente Ruby oficial para a [API v3 da Clicksign](https://developers.clicksign.c
 
 **Requisitos:** Ruby >= 3.0 · dependências de runtime: apenas biblioteca padrão (`net/http`, `json`).
 
-**Documentação:** [índice `docs/`](docs/) · [Workflow](docs/WORKFLOW.md) · [Cookbook](docs/cookbook/) · [Troubleshooting](docs/TROUBLESHOOTING.md) · [Arquitetura](docs/ARCHITECTURE.md) · [Observabilidade](docs/OBSERVABILITY.md) · [SPEC](docs/SPEC.md) · API: [Sandbox](https://sandbox.clicksign.com/api/v3) · [Produção](https://app.clicksign.com/api/v3)
+**Documentação:** [índice `docs/`](docs/) · [Workflow](docs/WORKFLOW.md) · [Cookbook](docs/examples/) · [Troubleshooting](docs/TROUBLESHOOTING.md) · [Arquitetura](docs/ARCHITECTURE.md) · [Observabilidade](docs/OBSERVABILITY.md) · [SPEC](docs/SPEC.md) · API: [Sandbox](https://sandbox.clicksign.com/api/v3) · [Produção](https://app.clicksign.com/api/v3)
 
 ---
 
@@ -31,7 +31,7 @@ Cliente Ruby oficial para a [API v3 da Clicksign](https://developers.clicksign.c
 
 > **Exemplo passo a passo:** [`docs/WORKFLOW.md`](docs/WORKFLOW.md) — fluxo completo de envelope → documento → signatário → requisitos → ativação → notificação.
 
-> **Cookbook (receitas por cenário):** [`docs/cookbook/`](docs/cookbook/) — [retries](docs/cookbook/01-retries.md), [bulk requirements](docs/cookbook/02-bulk-requirements.md), [webhooks](docs/cookbook/03-webhooks.md), [vários clientes](docs/cookbook/04-multi-client.md), [list vs filter](docs/cookbook/07-list-and-filter.md), [limitações de produção](docs/cookbook/08-production-limitations.md).
+> **Cookbook (receitas por cenário):** [`docs/examples/`](docs/examples/) — [retries](docs/examples/01-retries.md), [bulk requirements](docs/examples/02-bulk-requirements.md), [webhooks](docs/examples/03-webhooks.md), [vários clientes](docs/examples/04-multi-client.md), [list vs filter](docs/examples/07-list-and-filter.md), [limitações de produção](docs/examples/08-production-limitations.md).
 
 > **Troubleshooting:** [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — sintoma → causa → correção (erros HTTP, multi-tenant, bulk parcial, webhooks).
 
@@ -507,7 +507,7 @@ Event.create(
 
 `list` **não** aceita argumentos. Para filtrar: `Envelope.filter(status: 'draft').to_a` (não `Envelope.list(status: 'draft')`).
 
-Guia completo: [`docs/cookbook/07-list-and-filter.md`](docs/cookbook/07-list-and-filter.md).
+Guia completo: [`docs/examples/07-list-and-filter.md`](docs/examples/07-list-and-filter.md).
 
 ```ruby
 # Sem filtros — retorna Array imediatamente
@@ -720,7 +720,7 @@ Cada request abre e fecha uma conexão TCP (via `Net::HTTP.start`). Não há reu
 - **OK** para jobs sequenciais, integrações moderadas e a maioria dos apps Rails.
 - **Atenção** em Puma com muitas threads e várias chamadas Clicksign por request: overhead de handshake/TLS pode virar gargalo antes do rate limit da API.
 
-Mitigações: menos round-trips (`BulkRequirement`, batch na app), filas (Sidekiq), cache de leitura. Detalhes: [`docs/cookbook/08-production-limitations.md`](docs/cookbook/08-production-limitations.md).
+Mitigações: menos round-trips (`BulkRequirement`, batch na app), filas (Sidekiq), cache de leitura. Detalhes: [`docs/examples/08-production-limitations.md`](docs/examples/08-production-limitations.md).
 
 ### `Thread.current` e Fibers
 
@@ -765,7 +765,7 @@ lib/clicksign/
 docs/SPEC.md             # mapa completo de resources e rotas
 docs/WORKFLOW.md         # fluxo notarial ponta a ponta
 docs/README.md           # índice da documentação
-docs/cookbook/           # receitas: retries, bulk, webhooks, multi-cliente
+docs/examples/           # receitas: retries, bulk, webhooks, multi-cliente
 docs/TROUBLESHOOTING.md  # diagnóstico e erros comuns
 docs/ARCHITECTURE.md     # diagramas e camadas
 docs/OBSERVABILITY.md    # logs, métricas, OpenTelemetry

data/REVISION

@@ -0,0 +1 @@
+0.1.8

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: 3)
       @api_key       = api_key
       @base_url      = base_url
       @open_timeout  = open_timeout
@@ -42,6 +42,13 @@ module Clicksign
       execute_with_retry(request, uri)
     end
 
+    def put(path, body:)
+      uri = build_uri(path)
+      request = Net::HTTP::Put.new(uri, headers)
+      request.body = body.to_json
+      execute_with_retry(request, uri)
+    end
+
     def delete(path, body: nil)
       uri = build_uri(path)
       request = Net::HTTP::Delete.new(uri, headers)
@@ -70,7 +77,7 @@ module Clicksign
              Clicksign::ServerError => e
         raise unless e.retryable? && attempts <= @max_retries
 
-        delay = RetryBackoff.delay(attempts)
+        delay = RetryBackoff.retry_delay(attempts, e.response_headers)
         publish_retry(request, uri, attempts, e, delay)
         sleep(delay)
         retry
@@ -82,8 +89,9 @@ module Clicksign
       context = request_context(request, uri, attempt)
       response = http_request(request, uri)
       handle_response(response, context, start)
-    rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
-      handle_network_error(e, context, elapsed_ms(start))
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
+           Errno::ECONNREFUSED => e
+      handle_network_error(e, context, start)
     end
 
     def http_request(request, uri)

data/lib/clicksign/configuration.rb

@@ -15,7 +15,7 @@ module Clicksign
       @open_timeout  = 2
       @read_timeout  = 10
       @write_timeout = 10
-      @max_retries   = 0
+      @max_retries   = 3
     end
 
     def environment=(env)

data/lib/clicksign/error_handler.rb

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

data/lib/clicksign/json_api/atomic_results_parser.rb

@@ -24,6 +24,7 @@ module Clicksign
       end
 
       def build_operation_result(slot:, index:, op:, envelope_id:)
+        slot ||= {}
         errors = slot['errors']
         requirement = build_requirement(slot['data'], envelope_id: envelope_id)
 
@@ -37,7 +38,7 @@ module Clicksign
       end
 
       def build_requirement(data, envelope_id:)
-        return nil if data.nil? || data.empty?
+        return nil if data.nil? || (!data['id'] && !data['type'])
 
         Resources::Notarial::Requirement.send(
           :build_instance,
@@ -54,7 +55,7 @@ module Clicksign
       def format_errors(errors)
         return 'Validation failed' unless errors.is_a?(Array)
 
-        errors.filter_map { |e| e['detail'] || e['title'] }.join(', ')
+        errors.filter_map { |e| e.is_a?(Hash) && (e['detail'] || e['title']) }.join(', ')
       end
     end
   end

data/lib/clicksign/json_api/bulk_operations_client.rb

@@ -43,7 +43,8 @@ module Clicksign
         begin
           attempts += 1
           execute_once(request, uri, attempt: attempts)
-        rescue Clicksign::TimeoutError => e
+        rescue Clicksign::TimeoutError, Clicksign::RateLimitError,
+               Clicksign::ServerError => e
           raise unless e.retryable? && attempts <= @max_retries
 
           delay = RetryBackoff.delay(attempts)
@@ -64,8 +65,8 @@ module Clicksign
       end
 
       def handle_bulk_body(response, context, status, duration)
-        parsed = parse_response_body(response) || {}
-        return parsed if parsed.key?('atomic:results')
+        parsed = parse_response_body(response)
+        return parsed if parsed&.key?('atomic:results')
 
         begin
           ErrorHandler.call(response)
@@ -73,7 +74,7 @@ module Clicksign
           publish_http_error(context, e, status, duration)
           raise
         end
-        parsed
+        parsed || {}
       end
 
       def http_post(request, uri)

data/lib/clicksign/json_api/parser.rb

@@ -4,11 +4,14 @@ module Clicksign
   module JsonApi
     module Parser
       def self.parse(raw)
+        return { data: [], included: [], links: nil } if raw.nil?
+
         raw_data = raw['data']
         data = case raw_data
                when Array then raw_data.map { |item| build(item) }
                when Hash  then [build(raw_data)]
-               else            []
+               when nil   then []
+               else raise Error, "Unexpected JSON:API data type: #{raw_data.class}"
                end
 
         included = Array(raw['included'])

data/lib/clicksign/json_api/serializer.rb

@@ -3,8 +3,8 @@
 module Clicksign
   module JsonApi
     module Serializer
-      def self.dump(type:, attributes:, id: nil, relationships: {})
-        data = { type: type, attributes: attributes }
+      def self.dump(type:, attributes: {}, id: nil, relationships: {})
+        data = { type: type, attributes: attributes || {} }
         data[:id] = id if id
         data[:relationships] = relationships unless relationships.empty?
         { data: data }

data/lib/clicksign/resource.rb

@@ -232,7 +232,7 @@ module Clicksign
           return true
         end
 
-        items.size >= per
+        per.positive? && items.size >= per
       end
 
       def build_instance(data, parent_id: nil)

data/lib/clicksign/resources/folder.rb

@@ -15,7 +15,9 @@ module Clicksign
       end
 
       def child_folder_ids
-        Array(relationships.dig('folders', 'data')).filter_map { |d| d['id'] }
+        Array(relationships.dig('folders', 'data')).filter_map do |d|
+          d.is_a?(Hash) ? d['id'] : nil
+        end
       end
     end
   end

data/lib/clicksign/resources/membership.rb

@@ -13,6 +13,21 @@ module Clicksign
         )
       end
 
+      def update(**attributes)
+        raw = self.class.client.put(
+          "#{base_path}/#{@id}",
+          body: JsonApi::Serializer.dump(
+            type: self.class.resource_type, id: @id, attributes: attributes,
+          ),
+        )
+        parsed = JsonApi::Parser.parse(raw)
+        data   = parsed[:data].first
+        raise NotFoundError, 'API returned null data' if data.nil?
+
+        load_data(data, parent_id: @_parent_id)
+        self
+      end
+
       def user_id
         relationships.dig('user', 'data', 'id')
       end

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

@@ -42,6 +42,10 @@ module Clicksign
         end
 
         def self.create(envelope_id:, &block)
+          if envelope_id.nil? || envelope_id.to_s.empty?
+            raise ArgumentError,
+              'envelope_id is required'
+          end
           raise ArgumentError, 'block is required' unless block
 
           ops = JsonApi::Operations::BulkRequirement.new

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

@@ -28,7 +28,13 @@ module Clicksign
         end
 
         def base_path
-          "/envelopes/#{@_parent_id || envelope_id}/documents"
+          eid = @_parent_id || envelope_id
+          if eid.nil?
+            raise Clicksign::Error,
+              'envelope_id is required for Document operations'
+          end
+
+          "/envelopes/#{eid}/documents"
         end
 
         def envelope_id

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

@@ -6,6 +6,8 @@ module Clicksign
       class Event < Clicksign::Resource
         self.resource_type = 'events'
 
+        # Known custom event kinds. Override or append to extend without SDK update:
+        #   Clicksign::Resources::Notarial::Event::CUSTOM_KINDS << 'new_kind'
         CUSTOM_KINDS = %w[token_email token_sms].freeze
 
         def self.create(envelope_id:, document_id:, **attributes)

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

@@ -42,8 +42,19 @@ module Clicksign
         end
         private_class_method :list_related
 
+        def update(**)
+          raise NotImplementedError,
+            'Requirement does not support update (API does not provide this endpoint)'
+        end
+
         def base_path
-          "/envelopes/#{@_parent_id || envelope_id}/requirements"
+          eid = @_parent_id || envelope_id
+          if eid.nil?
+            raise Clicksign::Error,
+              'envelope_id is required for Requirement operations'
+          end
+
+          "/envelopes/#{eid}/requirements"
         end
 
         def envelope_id

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

@@ -22,7 +22,13 @@ module Clicksign
         end
 
         def base_path
-          "/envelopes/#{@_parent_id || envelope_id}/signature_watchers"
+          eid = @_parent_id || envelope_id
+          if eid.nil?
+            raise Clicksign::Error,
+              'envelope_id is required for SignatureWatcher operations'
+          end
+
+          "/envelopes/#{eid}/signature_watchers"
         end
 
         def update(**)

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

@@ -44,7 +44,13 @@ module Clicksign
         end
 
         def base_path
-          "/envelopes/#{@_parent_id || envelope_id}/signers"
+          eid = @_parent_id || envelope_id
+          if eid.nil?
+            raise Clicksign::Error,
+              'envelope_id is required for Signer operations'
+          end
+
+          "/envelopes/#{eid}/signers"
         end
 
         def envelope_id

data/lib/clicksign/retry_backoff.rb

@@ -18,5 +18,22 @@ module Clicksign
 
       rng.rand(max)
     end
+
+    def parse_retry_after(headers)
+      return nil unless headers.is_a?(Hash)
+
+      raw = headers['retry-after'] || headers['Retry-After']
+      return nil if raw.nil? || raw.to_s.strip.empty?
+
+      Float(raw.to_s.strip)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def retry_delay(attempt, headers = nil, rng: Random)
+      jitter      = delay(attempt, rng: rng)
+      retry_after = parse_retry_after(headers)
+      retry_after ? [jitter, retry_after].max : jitter
+    end
   end
 end

data/lib/clicksign/webhook.rb

@@ -25,18 +25,21 @@ module Clicksign
 
     # Computes the expected Content-HMAC value for a given payload and secret.
     def self.compute_signature(payload, secret:)
+      raise ArgumentError, 'secret must not be empty' if secret.nil? || secret.empty?
+
       "#{DIGEST}=#{OpenSSL::HMAC.hexdigest(DIGEST, secret, payload)}"
     end
 
     # Constant-time comparison to prevent timing attacks.
     def self.secure_compare?(expected, actual)
-      return false if actual.nil? || actual.to_s.empty?
+      return false if actual.nil?
+
+      actual_str = actual.is_a?(String) ? actual : actual.to_s
+      return false if actual_str.empty?
 
-      digest_a = OpenSSL::Digest::SHA256.hexdigest(expected)
-      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?
+      OpenSSL.fixed_length_secure_compare(expected, actual_str)
+    rescue ArgumentError
+      false
     end
     private_class_method :secure_compare?
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clicksign-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.8
 platform: ruby
 authors:
 - Clicksign
@@ -17,6 +17,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- REVISION
 - lib/clicksign.rb
 - lib/clicksign/client.rb
 - lib/clicksign/configuration.rb