clicksign-ruby-sdk 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b00cbdd7f7cbfb7b8eb0d97e2a89b5578bbfa93474e81a021498dd8bd4d65bf
-  data.tar.gz: '049906ba475373a2d7862fa27872ae58037c5f056149ae95d8065d3f36928bd0'
+  metadata.gz: a45728b201a9703e1d70cb6de98056f85da9a524d9d0c122a1ed951d6f98ef5b
+  data.tar.gz: 7a2aea99029254b4849b27090f40927d4cbf66d44cb516f121ea14c65544f141
 SHA512:
-  metadata.gz: f488769e30736ddee12363827d8f73bfb5671db3dacbff62d1c83ed20f25aafc1ed4a9255a658170d9ad190fcb2d85d9b12843866bac3979e540cce1a8f0a599
-  data.tar.gz: 35e43651dbca0ddb24831c2d85a93a948765854af07c6544bb78aaef7509f3d7e92fe7847f2c0fea0e4bf53d84edb291786aacc171563ccab19cbcf76b2fe616
+  metadata.gz: e9cb3bdaff221f8a8e58a9ef4ca47363962e19b7dcb4f22eb129cb1f5f3b60812550db76301ee8a36473be11490293932895d83c91ef60d10928206d090cd162
+  data.tar.gz: 8c3cd41e15ba5c21136fc3ee4b53fcb96c231620735c17401acbd046a032262b31a9a1617f07ec704e9a9593dedb8023dd82019afe156cee782356c78c297199

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 da API:** [Sandbox](https://sandbox.clicksign.com/api/v3) · [Produção](https://app.clicksign.com/api/v3) · Referência interna: [`docs/SPEC.md`](docs/SPEC.md)
+**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)
 
 ---
 
@@ -17,17 +17,26 @@ Cliente Ruby oficial para a [API v3 da Clicksign](https://developers.clicksign.c
 
 - [Instalação](#instalação)
 - [Configuração](#configuração)
+- [Multi-conta e cliente instanciável](#multi-conta-e-cliente-instantiável)
+- [Timeouts, retry e instrumentação](#timeouts-retry-e-instrumentação)
 - [Início rápido](#início-rápido)
 - [Fluxo de assinatura (notarial)](#fluxo-de-assinatura-notarial)
 - [Filtros, ordenação e paginação](#filtros-ordenação-e-paginação)
 - [Outros recursos](#outros-recursos)
 - [Tratamento de erros](#tratamento-de-erros)
 - [Ambientes](#ambientes)
+- [Limitações e produção](#limitações-e-produção)
 - [Desenvolvimento](#desenvolvimento)
 - [Licença](#licença)
 
 > **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).
+
+> **Troubleshooting:** [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — sintoma → causa → correção (erros HTTP, multi-tenant, bulk parcial, webhooks).
+
+> **Arquitetura e observabilidade:** [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · [`docs/OBSERVABILITY.md`](docs/OBSERVABILITY.md)
+
 ---
 
 ## Instalação
@@ -56,21 +65,40 @@ gem install clicksign-ruby-sdk
 
 ## Configuração
 
-Configure a chave de API e a URL base **uma vez** no boot da aplicação (initializer, `config/initializers/clicksign.rb`, script, etc.):
+A forma mais simples é a configuração global no boot da aplicação (initializer, `config/initializers/clicksign.rb`, script, etc.):
 
 ```ruby
 require 'clicksign'
 
 Clicksign.configure do |c|
   c.api_key  = ENV.fetch('CLICKSIGN_API_KEY')
-  c.base_url = ENV.fetch('CLICKSIGN_API_BASE_URL', 'https://sandbox.clicksign.com/api/v3')
+  c.environment = :sandbox   # ou :production — define base_url automaticamente
+  # c.base_url = '...'      # opcional: sobrescreve o URL do ambiente
+  c.open_timeout  = 2       # segundos (padrão)
+  c.read_timeout  = 10
+  c.write_timeout = 10
+  c.max_retries   = 0       # retentativas automáticas (ver seção abaixo)
 end
 ```
 
+| Opção | Padrão | Descrição |
+|-------|--------|-----------|
+| `api_key` | — | Token da API (obrigatório) |
+| `environment` | — | `:sandbox` ou `:production` (atalho para `base_url`) |
+| `base_url` | produção | URL completa da API v3 |
+| `open_timeout` | `2` | Timeout de conexão (s) |
+| `read_timeout` | `10` | Timeout de leitura (s) |
+| `write_timeout` | `10` | Timeout de escrita (s) |
+| `max_retries` | `0` | Retentativas em erros transitórios |
+
 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:
 
 ```bash
@@ -79,6 +107,126 @@ CLICKSIGN_API_KEY=seu-token bundle exec ruby bin/console
 
 ---
 
+## Multi-conta e cliente instanciável
+
+Além da config global, a gem oferece clientes isolados por contexto — útil em apps multi-tenant, jobs Sidekiq com token por conta e testes paralelos.
+
+### `Clicksign::Services` (recomendado para resources)
+
+Encapsula um `Clicksign::Client` e roteia todas as chamadas de `Clicksign::Resources::*` dentro do bloco `use`:
+
+```ruby
+conta_a = Clicksign::Services.new(
+  api_key: ENV['CLICKSIGN_TOKEN_CONTA_A'],
+  environment: :production,
+  max_retries: 2
+)
+
+conta_b = Clicksign::Services.new(
+  api_key: ENV['CLICKSIGN_TOKEN_CONTA_B'],
+  environment: :sandbox
+)
+
+conta_a.use do
+  Clicksign::Resources::Notarial::Envelope.create(name: 'Contrato A')
+end
+
+conta_b.use do
+  Clicksign::Resources::Notarial::Envelope.filter(status: 'draft').to_a
+end
+```
+
+O client ativo fica em `Thread.current` durante o bloco; blocos aninhados restauram o client externo ao sair. Fora de `use`, os resources voltam a usar `Clicksign.client` (config global).
+
+Em Rails, um padrão comum é resolver o service no controller e executar a lógica dentro de `use`:
+
+```ruby
+class EnvelopesController < ApplicationController
+  def create
+    current_tenant.clicksign_service.use do
+      envelope = Clicksign::Resources::Notarial::Envelope.create(envelope_params)
+      render json: { id: envelope.id }
+    end
+  end
+end
+```
+
+### `Clicksign::Client` (HTTP direto)
+
+Para chamadas JSON:API de baixo nível sem passar pelos resources:
+
+```ruby
+client = Clicksign::Client.new(
+  api_key: ENV['CLICKSIGN_API_KEY'],
+  base_url: 'https://sandbox.clicksign.com/api/v3',
+  open_timeout: 2,
+  read_timeout: 30,
+  max_retries: 3
+)
+
+response = client.get('/envelopes', params: { 'filter[status]' => 'draft' })
+client.post('/envelopes', body: { data: { type: 'envelopes', attributes: { name: 'Novo' } } })
+```
+
+| Abordagem | Quando usar |
+|-----------|-------------|
+| `Clicksign.configure` | App single-tenant; initializer único |
+| `Clicksign::Services#use` | Multi-conta; token por request/job |
+| `Clicksign::Client.new` | Controle fino do HTTP ou integração customizada |
+
+---
+
+## Timeouts, retry e instrumentação
+
+### Timeouts
+
+Configuráveis globalmente (`Clicksign.configure`), por `Services` ou diretamente em `Client.new`. Timeouts de rede disparam `Clicksign::TimeoutError` (retryable quando `max_retries > 0`).
+
+### Retry automático
+
+Com `max_retries > 0`, o client reexecuta a requisição em erros **transitórios**:
+
+- `Clicksign::TimeoutError`
+- `Clicksign::RateLimitError`
+- `Clicksign::ServerError` (5xx)
+
+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|
+  c.api_key     = ENV['CLICKSIGN_API_KEY']
+  c.environment = :production
+  c.max_retries = 3
+end
+```
+
+Operações em lote (`BulkRequirement`) usam o mesmo `max_retries` e os mesmos hooks de instrumentação via `Clicksign.bulk_operations_client` (retry automático só em timeout).
+
+### Instrumentação
+
+Registre callbacks para observabilidade (logs, métricas, APM). Callbacks não propagam exceções — falhas internas são ignoradas para não afetar a requisição.
+
+```ruby
+Clicksign.on_request do |event|
+  # event: :method, :path, :status, :duration_ms, :attempt
+  Rails.logger.info "[Clicksign] #{event[:method]} #{event[:path]} → #{event[:status]} (#{event[:duration_ms]}ms)"
+end
+
+Clicksign.on_retry do |event|
+  # event: :method, :path, :attempt, :max_retries, :error, :wait_ms
+  Rails.logger.warn "[Clicksign] retry #{event[:attempt]}/#{event[:max_retries]} em #{event[:wait_ms]}ms"
+end
+
+Clicksign.on_error do |event|
+  # event: :method, :path, :error, :status, :duration_ms
+  Sentry.capture_exception(event[:error])
+end
+```
+
+Eventos publicados: `:request` (toda tentativa, sucesso ou erro HTTP), `:retry` (antes de cada retentativa), `:error` (quando uma exceção é lançada).
+
+---
+
 ## Início rápido
 
 Listar envelopes em rascunho e criar um novo:
@@ -316,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 }
 )
 ```
 
@@ -329,23 +498,40 @@ Event.create_for_document(
 
 ## Filtros, ordenação e paginação
 
-A API de listagem é chainable:
+### `list` vs `filter`
+
+| Método | Retorno | Uso |
+|--------|---------|-----|
+| `Resource.list` | `Array` | Primeira página da collection, **sem** filtros na chain |
+| `Resource.filter(...)` | `QueryProxy` | Filtros, ordenação, paginação, includes — termine com `.to_a`, `.first`, `.auto_paging_each`, etc. |
+
+`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).
+
+```ruby
+# Sem filtros — retorna Array imediatamente
+Webhook.list
+
+# Com filtros ou chain — começa em filter
+Envelope.filter(status: 'draft').to_a
+```
+
+### Chain de consulta
 
 ```ruby
 Envelope
   .filter(status: 'running', name: 'Contrato')
+  .with_includes('folder')   # sideload JSON:API (.include('folder') também funciona)
   .order('-created')
   .page(1)
   .per(20)
   .to_a
 
-# Atalho quando há poucos filtros
 Template.filter(name: 'NDA padrão').first
 
-# Navegação no resultado
-Envelope.order('-created').first   # mais recente
-Envelope.order('-created').last    # mais antigo
-Envelope.filter(status: 'draft').count  # total de rascunhos
+Envelope.order('-created').first
+Envelope.filter(status: 'draft').count
 ```
 
 Atributos dos objetos retornados são acessados como métodos ou por chave string:
@@ -364,6 +550,8 @@ Envelope.filter(status: 'running').map(&:name)
 Envelope.order('-created').select { |e| e.auto_close }
 ```
 
+Percorrer **todas** as páginas automaticamente (`auto_paging_each`, `each_page`, `auto_paging`): a gem segue `links.next` da JSON:API quando presente; se a API não enviar `links`, usa heurística por `page[size]`.
+
 ---
 
 ## Outros recursos
@@ -372,8 +560,8 @@ Envelope.order('-created').select { |e| e.auto_close }
 |---------|--------|---------|
 | Webhook | `Clicksign::Resources::Webhook` | `Webhook.create(endpoint: 'https://...', events: ['envelope.completed'], status: 'active')` |
 | Pasta | `Clicksign::Resources::Folder` | `Folder.create(name: 'Contratos 2026', folder_id: pai&.id)` |
-| Template | `Clicksign::Resources::Template` | `Template.list` · `Template.list_template_fields(id)` |
-| Usuário | `Clicksign::Resources::User` | `User.me` · `User.filter(email: '...')` |
+| Template | `Clicksign::Resources::Template` | `Template.list` · `Template.filter(name: '...')` · `Template.list_template_fields(id)` |
+| Usuário | `Clicksign::Resources::User` | `User.me` · `User.list` · `User.filter(email: '...')` |
 | Membership | `Clicksign::Resources::Membership` | `Membership.create(role: 'member', user_id: user.id)` |
 | Grupo | `Clicksign::Resources::Group` | `Group.add_users(group_id, [user.id])` |
 | ACL pasta/grupo | `Clicksign::Resources::AccessControlList` | `AccessControlList.create(folder_id:, group_id:)` |
@@ -453,15 +641,22 @@ AccessControlList.destroy(folder_id: folder.id, group_id: group.id)
 
 Erros HTTP são convertidos em exceções antes de chegar ao seu código:
 
-| HTTP | Exceção |
-|------|---------|
-| 401, 403 | `Clicksign::AuthenticationError` |
-| 404 | `Clicksign::NotFoundError` |
-| 400, 422 | `Clicksign::ValidationError` |
-| 409 | `Clicksign::ConflictError` |
-| 429 | `Clicksign::RateLimitError` |
-| 5xx | `Clicksign::ServerError` |
-| Timeout / conexão | `Clicksign::TimeoutError` |
+| HTTP | Exceção | `retryable?` |
+|------|---------|--------------|
+| 401, 403 | `Clicksign::AuthenticationError` | não |
+| 404 | `Clicksign::NotFoundError` | não |
+| 400, 422 | `Clicksign::ValidationError` | não |
+| 409 | `Clicksign::ConflictError` | não |
+| 429 | `Clicksign::RateLimitError` | sim |
+| 5xx | `Clicksign::ServerError` | sim |
+| Timeout / conexão | `Clicksign::TimeoutError` | sim |
+
+Todas herdam de `Clicksign::Error` e expõem metadados úteis para debug:
+
+- `status_code` — código HTTP da resposta
+- `request_id` — quando enviado pela API
+- `response_body` — corpo JSON da resposta de erro
+- `response_headers` — headers da resposta (`RateLimitError` também expõe `rate_limit_remaining` e `rate_limit_reset`)
 
 Exemplo:
 
@@ -472,6 +667,9 @@ rescue Clicksign::NotFoundError
   puts 'Envelope não encontrado'
 rescue Clicksign::ValidationError => e
   puts "Dados inválidos: #{e.message}"
+  puts e.response_body
+rescue Clicksign::RateLimitError => e
+  puts "Aguarde reset em #{e.rate_limit_reset}" if e.retryable?
 rescue Clicksign::AuthenticationError
   puts 'Verifique CLICKSIGN_API_KEY'
 end
@@ -479,28 +677,62 @@ end
 
 Operações em lote (`BulkRequirement`) podem retornar falhas **por slot** em `response.failures` sem lançar exceção, quando a API responde com `atomic:results` parcial.
 
+Guia detalhado: [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md).
+
 ---
 
 ## Ambientes
 
-| Ambiente | `base_url` |
-|----------|------------|
-| Sandbox | `https://sandbox.clicksign.com/api/v3` |
-| Produção | `https://app.clicksign.com/api/v3` |
+| Ambiente | Símbolo | `base_url` |
+|----------|---------|------------|
+| Sandbox | `:sandbox` | `https://sandbox.clicksign.com/api/v3` |
+| Produção | `:production` | `https://app.clicksign.com/api/v3` |
 
-O padrão da gem em `Clicksign::Configuration` é produção (`app.clicksign.com`). Para desenvolvimento, defina explicitamente o sandbox:
+O padrão em `Clicksign::Configuration` é **produção**. Para desenvolvimento, use o atalho `environment` (equivalente a definir `base_url`):
 
 ```ruby
 Clicksign.configure do |c|
-  c.api_key  = ENV['CLICKSIGN_API_KEY']
-  c.base_url = 'https://sandbox.clicksign.com/api/v3'
+  c.api_key     = ENV['CLICKSIGN_API_KEY']
+  c.environment = :sandbox
 end
+
+# Ou em multi-conta:
+service = Clicksign::Services.new(
+  api_key: ENV['CLICKSIGN_API_KEY'],
+  environment: :sandbox
+)
 ```
 
+Também é possível passar `base_url` manualmente quando precisar de um endpoint customizado (proxy, mock, etc.).
+
 Gere tokens de API no painel da Clicksign do ambiente correspondente.
 
 ---
 
+## Limitações e produção
+
+Design **stdlib-only** (`net/http`) — sem dependências de runtime extras. Duas limitações importantes em alta carga ou runtimes modernos:
+
+### Sem connection pool
+
+Cada request abre e fecha uma conexão TCP (via `Net::HTTP.start`). Não há reutilização persistente entre chamadas.
+
+- **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).
+
+### `Thread.current` e Fibers
+
+`Clicksign::Services#use` armazena o client em `Thread.current[:clicksign_client]`. Resources usam esse client dentro do bloco.
+
+- **Compatível:** Puma (thread por request), Sidekiq, scripts.
+- **Incompatível** com propagar contexto em **Fibers** (Falcon, async-ruby): o client do `use` pode não estar visível no Fiber que chama `Envelope.create`.
+
+Mitigações: `Clicksign.configure` por processo (single-tenant), `Clicksign::Client.new` explícito no seu contexto async, ou evitar `Services` em stacks fiberizadas.
+
+---
+
 ## Desenvolvimento
 
 Clone o repositório e instale dependências de desenvolvimento:
@@ -515,17 +747,28 @@ bundle exec rspec
 | `CLICKSIGN_API_KEY` | Token para testes contra sandbox (opcional) |
 | `CLICKSIGN_API_BASE_URL` | URL da API (padrão sandbox nos specs de integração legados) |
 
-A suíte principal usa **WebMock** e não exige rede. Alguns specs antigos ainda podem usar **VCR** com gravação no sandbox.
+A suíte usa **WebMock** e não exige rede.
 
 Estrutura relevante:
 
 ```
 lib/clicksign/
-  client.rb              # HTTP (GET, POST, PATCH, DELETE)
+  retry_backoff.rb       # Exponential backoff com full jitter
+  client.rb              # HTTP (GET, POST, PATCH, DELETE), retry, timeouts
+  services.rb            # Cliente por contexto (multi-conta via #use)
+  configuration.rb       # Config global, environment, timeouts, retry
+  request_instrumentation.rb  # Hooks compartilhados Client + BulkOperationsClient
+  instrumentation.rb     # Eventos :request, :retry, :error
   resource.rb            # CRUD base, filtros, nested lists
   resources/notarial/    # Envelope, Document, Signer, Requirement, ...
   json_api/              # Serializer, Parser, bulk operations
 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/TROUBLESHOOTING.md  # diagnóstico e erros comuns
+docs/ARCHITECTURE.md     # diagramas e camadas
+docs/OBSERVABILITY.md    # logs, métricas, OpenTelemetry
 ```
 
 ---

data/lib/clicksign/client.rb

@@ -6,13 +6,15 @@ require 'json'
 
 module Clicksign
   class Client
+    include RequestInstrumentation
+
     HEADERS = {
       'Content-Type' => 'application/vnd.api+json',
       'Accept' => 'application/vnd.api+json',
     }.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
@@ -68,24 +70,16 @@ module Clicksign
              Clicksign::ServerError => e
         raise unless e.retryable? && attempts <= @max_retries
 
-        delay = backoff_delay(attempts)
-        Instrumentation.publish(:retry, {
-                                  method: request.method.downcase.to_sym,
-                                  path: resource_path(uri),
-                                  attempt: attempts,
-                                  max_retries: @max_retries,
-                                  error: e,
-                                  wait_ms: (delay * 1000).round,
-                                })
+        delay = RetryBackoff.delay(attempts)
+        publish_retry(request, uri, attempts, e, delay)
         sleep(delay)
         retry
       end
     end
 
     def execute_once(request, uri, attempt: 1)
-      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      context = { method: request.method.downcase.to_sym, path: resource_path(uri),
-                  attempt: attempt }
+      start   = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      context = request_context(request, uri, attempt)
       response = http_request(request, uri)
       handle_response(response, context, start)
     rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
@@ -94,50 +88,24 @@ 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)
-      duration = elapsed_ms(start)
-      status   = response.code.to_i
+      _response, status, duration = publish_http_outcome(response, context, start)
       begin
         ErrorHandler.call(response)
       rescue Error => e
-        publish_event(:request, context, status: status, duration_ms: duration)
-        publish_event(:error, context, error: e, status: status, duration_ms: duration)
+        publish_http_error(context, e, status, duration)
         raise
       end
-      publish_event(:request, context, status: status, duration_ms: duration)
       return nil if response.body.nil? || response.body.empty?
 
       JSON.parse(response.body)
     end
-
-    def handle_network_error(error, context, duration)
-      err = TimeoutError.new(error.message)
-      publish_event(:error, context, error: err, status: nil, duration_ms: duration)
-      raise err, error.message, error.backtrace
-    end
-
-    def publish_event(type, context, extra)
-      Instrumentation.publish(type, context.merge(extra))
-    end
-
-    def elapsed_ms(start)
-      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
-    end
-
-    def resource_path(uri)
-      base = URI.parse(@base_url).path
-      uri.path.delete_prefix(base)
-    end
-
-    def backoff_delay(attempt)
-      [0.5 * (2**(attempt - 1)), 30].min
-    end
   end
 end

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
+      :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,20 +13,24 @@ 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
-          # Callbacks must not affect the request — errors are silently ignored.
+        rescue StandardError => e
+          Clicksign.configuration.logger&.warn(
+            "[Clicksign] instrumentation callback error (#{event}): " \
+            "#{e.class}: #{e.message}",
+          )
         end
       end
 
       # 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

@@ -7,13 +7,15 @@ require 'json'
 module Clicksign
   module JsonApi
     class BulkOperationsClient
+      include RequestInstrumentation
+
       HEADERS = {
         'Content-Type' => 'application/vnd.api+json',
         'Accept' => 'application/vnd.api+json',
       }.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
@@ -23,23 +25,13 @@ module Clicksign
       end
 
       def post(path, body:)
-        response = perform_post(path, body)
-        parsed = parse_response_body(response) || {}
-
-        return parsed if parsed.key?('atomic:results')
-
-        ErrorHandler.call(response)
-        parsed
-      end
-
-      private
-
-      def perform_post(path, body)
         uri     = build_uri(path)
         request = build_request(uri, body)
         execute_with_retry(request, uri)
       end
 
+      private
+
       def build_request(uri, body)
         request = Net::HTTP::Post.new(uri, headers)
         request.body = body.to_json
@@ -50,29 +42,47 @@ module Clicksign
         attempts = 0
         begin
           attempts += 1
-          safe_http_post(request, uri)
+          execute_once(request, uri, attempt: attempts)
         rescue Clicksign::TimeoutError => e
           raise unless e.retryable? && attempts <= @max_retries
 
-          sleep([0.5 * (2**(attempts - 1)), 30].min)
+          delay = RetryBackoff.delay(attempts)
+          publish_retry(request, uri, attempts, e, delay)
+          sleep(delay)
           retry
         end
       end
 
-      def safe_http_post(request, uri)
-        http_post(request, uri)
+      def execute_once(request, uri, attempt: 1)
+        start   = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        context = request_context(request, uri, attempt)
+        response = http_post(request, uri)
+        _response, status, duration = publish_http_outcome(response, context, start)
+        handle_bulk_body(response, context, status, duration)
       rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
-        raise TimeoutError, e.message, e.backtrace
+        handle_network_error(e, context, start)
+      end
+
+      def handle_bulk_body(response, context, status, duration)
+        parsed = parse_response_body(response) || {}
+        return parsed if parsed.key?('atomic:results')
+
+        begin
+          ErrorHandler.call(response)
+        rescue Error => e
+          publish_http_error(context, e, status, duration)
+          raise
+        end
+        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) do |http|
-          http.request(request)
-        end
+          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
@@ -87,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

@@ -15,7 +15,9 @@ module Clicksign
                    .select { |item| item.is_a?(Hash) && item['type'] }
                    .map { |item| build(item) }
 
-        { data: data, included: included }
+        links = raw['links'] if raw.key?('links')
+
+        { data: data, included: included, links: links }
       end
 
       def self.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/request_instrumentation.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module RequestInstrumentation
+    private
+
+    def publish_event(type, context, extra)
+      Instrumentation.publish(type, context.merge(extra))
+    end
+
+    def elapsed_ms(start)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+    end
+
+    def resource_path(uri)
+      base = URI.parse(@base_url).path
+      uri.path.delete_prefix(base)
+    end
+
+    def request_context(request, uri, attempt)
+      {
+        method: request.method.downcase.to_sym,
+        path: resource_path(uri),
+        attempt: attempt,
+      }
+    end
+
+    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,
+      })
+    end
+
+    def handle_network_error(error, context, start)
+      duration = elapsed_ms(start)
+      err = TimeoutError.new(error.message)
+      publish_event(:error, context, error: err, status: nil, duration_ms: duration)
+      raise err, error.message, error.backtrace
+    end
+
+    def publish_http_outcome(response, context, start)
+      duration = elapsed_ms(start)
+      status   = response.code.to_i
+      publish_event(:request, context, status: status, duration_ms: duration)
+      [response, status, duration]
+    end
+
+    def publish_http_error(context, error, status, duration)
+      publish_event(:error, context, error: error, status: status, duration_ms: duration)
+    end
+  end
+end

data/lib/clicksign/resource.rb

@@ -15,11 +15,15 @@ module Clicksign
         self
       end
 
-      def include(*types)
+      def with_includes(*types)
         @builder.include(*types)
         self
       end
 
+      def include(*types)
+        with_includes(*types)
+      end
+
       def order(field)
         @builder.order(field)
         self
@@ -90,10 +94,10 @@ module Clicksign
         @endpoint || "/#{resource_type}"
       end
 
-      def list(**filters)
-        return fetch_list({}) if filters.empty?
-
-        filter(**filters).to_a
+      # Returns the first page with no query chain.
+      # Use +filter+ for filters, sort, pagination.
+      def list
+        fetch_list({})
       end
 
       def retrieve(id)
@@ -118,10 +122,28 @@ module Clicksign
         QueryProxy.new(self, JsonApi::QueryBuilder.new.filter(**params))
       end
 
-      def include(*types)
+      # JSON:API sideload — use +with_includes+;
+      # +include+ also accepts +Module+ for Ruby mixins.
+      def with_includes(*types)
+        validate_jsonapi_include_types!(types)
         QueryProxy.new(self, JsonApi::QueryBuilder.new.include(*types))
       end
 
+      def include(*types)
+        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'
+        end
+        if modules.any?
+          modules.each { |mod| super(mod) }
+          return self
+        end
+
+        with_includes(*types)
+      end
+
       def order(field)
         QueryProxy.new(self, JsonApi::QueryBuilder.new.order(field))
       end
@@ -164,6 +186,17 @@ module Clicksign
         Thread.current[:clicksign_client] || Clicksign.client
       end
 
+      def validate_jsonapi_include_types!(types)
+        raise ArgumentError, 'at least one include type is required' if types.empty?
+
+        invalid = types.reject { |t| t.is_a?(String) || t.is_a?(Symbol) }
+        return if invalid.empty?
+
+        raise ArgumentError,
+          'JSON:API include types must be String or Symbol, ' \
+          "got: #{invalid.map(&:class).uniq.join(', ')}"
+      end
+
       private
 
       def fetch_list(params)
@@ -178,24 +211,41 @@ module Clicksign
         page = 1
 
         loop do
-          raw   = client.get(endpoint,
-                             params: base.merge('page[number]' => page,
-                                                'page[size]' => per))
-          items = JsonApi::Parser.parse(raw)[:data].map { |item| build_instance(item) }
+          raw    = client.get(endpoint,
+            params: base.merge('page[number]' => page,
+              'page[size]' => per))
+          parsed = JsonApi::Parser.parse(raw)
+          items  = parsed[:data].map { |item| build_instance(item) }
           yield items
-          break if items.size < per
+          break unless more_pages?(parsed, items, per)
 
           page += 1
         end
       end
 
+      def more_pages?(parsed, items, per)
+        links = parsed[:links]
+        unless links.nil?
+          next_link = links['next']
+          return false if next_link.nil? || next_link.to_s.empty?
+
+          return true
+        end
+
+        items.size >= per
+      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
       end
 
       def infer_resource_type
+        return 'resources' if name.nil? || name.empty?
+
         "#{name.split('::').last
               .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
               .gsub(/([a-z\d])([A-Z])/, '\1_\2')
@@ -213,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
 
@@ -225,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
 
@@ -239,11 +295,10 @@ module Clicksign
 
     def method_missing(name, *args, &block)
       key = name.to_s.delete_suffix('=')
-      if @_attributes&.key?(key)
-        name.to_s.end_with?('=') ? @_attributes[key] = args.first : @_attributes[key]
-      else
-        super
-      end
+      return super unless @_attributes&.key?(key)
+
+      @_attributes[key] = args.first if name.to_s.end_with?('=')
+      @_attributes[key]
     end
 
     def respond_to_missing?(name, include_private = false)

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/retry_backoff.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Clicksign
+  module RetryBackoff
+    BASE_SECONDS = 0.5
+    CAP_SECONDS  = 30.0
+
+    module_function
+
+    def ceiling(attempt)
+      [BASE_SECONDS * (2**(attempt - 1)), CAP_SECONDS].min.to_f
+    end
+
+    # Full jitter: uniform in [0, ceiling) to spread retries and avoid thundering herd.
+    def delay(attempt, rng: Random)
+      max = ceiling(attempt)
+      return 0.0 if max <= 0
+
+      rng.rand(max)
+    end
+  end
+end

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?

data/lib/clicksign.rb

@@ -9,6 +9,8 @@ require_relative 'clicksign/configuration'
 require_relative 'clicksign/errors'
 require_relative 'clicksign/error_handler'
 require_relative 'clicksign/instrumentation'
+require_relative 'clicksign/request_instrumentation'
+require_relative 'clicksign/retry_backoff'
 require_relative 'clicksign/webhook'
 require_relative 'clicksign/json_api/query_builder'
 require_relative 'clicksign/json_api/serializer'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clicksign-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Clicksign
@@ -30,6 +30,7 @@ files:
 - lib/clicksign/json_api/parser.rb
 - lib/clicksign/json_api/query_builder.rb
 - lib/clicksign/json_api/serializer.rb
+- lib/clicksign/request_instrumentation.rb
 - lib/clicksign/resource.rb
 - lib/clicksign/resources/acceptance_term/whatsapp.rb
 - lib/clicksign/resources/access_control_list.rb
@@ -49,6 +50,7 @@ files:
 - lib/clicksign/resources/template_field.rb
 - lib/clicksign/resources/user.rb
 - lib/clicksign/resources/webhook.rb
+- lib/clicksign/retry_backoff.rb
 - lib/clicksign/services.rb
 - lib/clicksign/version.rb
 - lib/clicksign/webhook.rb
@@ -75,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: []