clicksign-ruby-sdk 0.1.1 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c3da29608ca505f7705b718fa579adb1d346bf8000e50fc87382616833e645f
-  data.tar.gz: e92995a59c7939aac989d9a165956b9309523a505178a2f79f168e0b6b6578d5
+  metadata.gz: e2fa45c00d6994b4009e9888eb982da569f1657c692b7e83a5db76c69067ebc2
+  data.tar.gz: e74c86dab5a02752fd9bb3a388cf54c78ae90e9a376cdac163bf5dca090fd5e9
 SHA512:
-  metadata.gz: f1ccd82b00a37e3f88cd0e8fc65b0279500750ad8c008c8e98fb50451d22770440809e7d0308d01753e6a66c78dab72f151e949fcd3cfa9249dc9f10e9a5c1dd
-  data.tar.gz: c80bdcec1a9c6f7eb47b649cb17756c6cfde384d4fddfca8239b4efa2e26ccc415aa407aa7d83de852706b11571750ef94e1c8d2efa5e3265cb43efda3f9247d
+  metadata.gz: 86b4b41f6607d89ea58786225502c699902523d05ff72f60d983449fc9a318d794ab1c164ce1d475a073ea868d22ee65da53f7e36c61cb477e28e4cea7fa86f4
+  data.tar.gz: 484d16275cda5bf7e85413dcc3383776988574de052d6715a7d08e591d54701b13e3dd52a69c9a000977f8d51cc07a7590968050c6456b35cec48c914086a737

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,38 @@ 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.).
 
+> **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 +105,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 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.
+
+```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:
@@ -329,23 +475,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 +527,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 +537,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 +618,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 +644,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 +654,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 +724,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,6 +6,8 @@ require 'json'
 
 module Clicksign
   class Client
+    include RequestInstrumentation
+
     HEADERS = {
       'Content-Type' => 'application/vnd.api+json',
       'Accept' => 'application/vnd.api+json',
@@ -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
@@ -102,42 +96,16 @@ module Clicksign
     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'

data/lib/clicksign/instrumentation.rb

@@ -18,8 +18,11 @@ module Clicksign
       def publish(event, payload)
         @callbacks[event].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
 

data/lib/clicksign/json_api/bulk_operations_client.rb

@@ -7,6 +7,8 @@ require 'json'
 module Clicksign
   module JsonApi
     class BulkOperationsClient
+      include RequestInstrumentation
+
       HEADERS = {
         'Content-Type' => 'application/vnd.api+json',
         'Accept' => 'application/vnd.api+json',
@@ -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,19 +42,38 @@ 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)
@@ -70,9 +81,8 @@ module Clicksign
                         use_ssl: uri.scheme == 'https',
                         open_timeout: @open_timeout,
                         read_timeout: @read_timeout,
-                        write_timeout: @write_timeout) do |http|
-          http.request(request)
-        end
+                        write_timeout: @write_timeout,
+                        &proc { |http| http.request(request) })
       end
 
       def headers

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/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,17 +211,30 @@ 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)
         instance = allocate
         instance.send(:load_data, data, parent_id: parent_id)
@@ -196,6 +242,8 @@ module Clicksign
       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')
@@ -239,11 +287,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/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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clicksign
-  VERSION = '0.1.1'
+  VERSION = File.read(File.expand_path('../../REVISION', __dir__)).strip
 end

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.1
+  version: 0.1.4
 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