clicksign-ruby-sdk 0.1.4 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2fa45c00d6994b4009e9888eb982da569f1657c692b7e83a5db76c69067ebc2
-  data.tar.gz: e74c86dab5a02752fd9bb3a388cf54c78ae90e9a376cdac163bf5dca090fd5e9
+  metadata.gz: 5d76bec5fed9c775d1277ef1d0cd7158a87f7234d71fcd2fc8933a4421c8dba1
+  data.tar.gz: d18db7bdcf3825e7d266ff30609f9034c0a8e2fbb3d7f82352ae1e4a0c7ef0dd
 SHA512:
-  metadata.gz: 86b4b41f6607d89ea58786225502c699902523d05ff72f60d983449fc9a318d794ab1c164ce1d475a073ea868d22ee65da53f7e36c61cb477e28e4cea7fa86f4
-  data.tar.gz: 484d16275cda5bf7e85413dcc3383776988574de052d6715a7d08e591d54701b13e3dd52a69c9a000977f8d51cc07a7590968050c6456b35cec48c914086a737
+  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).
 
@@ -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 }
 )
 ```
 
@@ -484,7 +507,7 @@ Event.create_for_document(
 
 `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
@@ -697,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
 
@@ -742,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

@@ -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
@@ -82,17 +82,18 @@ 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)
       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/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

@@ -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
@@ -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,16 +73,16 @@ module Clicksign
           publish_http_error(context, e, status, duration)
           raise
         end
-        parsed
+        parsed || {}
       end
 
       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/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/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/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/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/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/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,11 @@ module Clicksign
       class Event < Clicksign::Resource
         self.resource_type = 'events'
 
-        def self.create_for_document(envelope_id:, document_id:, **attributes)
+        # 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)
           raw = client.post(
             "/envelopes/#{envelope_id}/documents/#{document_id}/events",
             body: JsonApi::Serializer.dump(type: resource_type, attributes: attributes),
@@ -14,6 +18,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/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,12 +22,18 @@ 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(**)
           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,11 +40,17 @@ 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
-          "/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/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

@@ -25,16 +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)
-      digest_a = OpenSSL::Digest::SHA256.hexdigest(expected)
-      digest_b = OpenSSL::Digest::SHA256.hexdigest(actual)
-      result = 0
-      digest_a.bytes.zip(digest_b.bytes) { |x, y| result |= x ^ y }
-      result.zero?
+      return false if actual.nil?
+
+      actual_str = actual.is_a?(String) ? actual : actual.to_s
+      return false if actual_str.empty?
+
+      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.4
+  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
@@ -77,7 +78,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: []