clicksign-ruby-sdk 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a45728b201a9703e1d70cb6de98056f85da9a524d9d0c122a1ed951d6f98ef5b
-  data.tar.gz: 7a2aea99029254b4849b27090f40927d4cbf66d44cb516f121ea14c65544f141
+  metadata.gz: 5d76bec5fed9c775d1277ef1d0cd7158a87f7234d71fcd2fc8933a4421c8dba1
+  data.tar.gz: d18db7bdcf3825e7d266ff30609f9034c0a8e2fbb3d7f82352ae1e4a0c7ef0dd
 SHA512:
-  metadata.gz: e9cb3bdaff221f8a8e58a9ef4ca47363962e19b7dcb4f22eb129cb1f5f3b60812550db76301ee8a36473be11490293932895d83c91ef60d10928206d090cd162
-  data.tar.gz: 8c3cd41e15ba5c21136fc3ee4b53fcb96c231620735c17401acbd046a032262b31a9a1617f07ec704e9a9593dedb8023dd82019afe156cee782356c78c297199
+  metadata.gz: d1f36573b8720bb2d5548540cabcb1b9d995b8cc6afb877e6b02844cef69a73af2708901c2f50dd43ca540db7f098c61077bfc9647a5e880928c361707da9069
+  data.tar.gz: d7b63661a2702eaaecfd59d65508964110965ed32a4dd26f273199951c7353f9761a8f5269389e8aec83044c3bc54562e458fa885180817f17b0ad19fec59b67

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.7

data/lib/clicksign/client.rb

@@ -82,8 +82,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/json_api/atomic_results_parser.rb

@@ -37,7 +37,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,

data/lib/clicksign/json_api/bulk_operations_client.rb

@@ -64,8 +64,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 +73,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,6 +4,8 @@ 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) }

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/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

@@ -43,7 +43,13 @@ module Clicksign
         private_class_method :list_related
 
         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/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.7
 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