assinafy 1.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f8b8c2701ec7f853e14b297d675829d16fef94b35f87d46cf372ef24d2d55482
+  data.tar.gz: d6cd90c3ad7304648f397544a118b9cd57dfd80db2a6a84ddea116878b515da8
+SHA512:
+  metadata.gz: 823b760bc2d019f2e6f77de43b6e199067b1030e5e1f2a75fde65ad87fa7cec51ae8dba59f357e388a27db945a814cc6ff0dd2be4be92e4d9c41a6b5cf5c272c
+  data.tar.gz: 5007b5ec7928af7dd1cc736cba63f9fc8efb72aa1478aedfad08bcaa28af2eec0c248e7903732b6e4b4c76fd73cd17f47a64535a266e33370e8d56b2b424e615

data/CHANGELOG.md

@@ -0,0 +1,168 @@
+# Changelog
+
+All notable changes to the `assinafy` Ruby gem are documented here.
+
+## 1.5.0
+
+### Added
+
+- **`Resources::AccountResource`** (`client.accounts`): `list`, `create`, `get`, `update`,
+  `delete` (with `force:`), `theme`, `stats`, and brand-logo `upload_logo`/`download_logo`/`delete_logo`.
+- **`Resources::UserResource`** (`client.users`): `me`, `stats`, and notification-preference
+  `GET`/`PUT` wrappers.
+- `DocumentResource#search` (`GET /accounts/{account_id}/documents/search`) and
+  `#rename` (`PATCH /documents/{document_id}`).
+- `AssignmentResource#list` (`GET /assignments`; the account context is sent as the
+  camelCase `accountId` query parameter, verified live).
+- `SignerDocumentResource#search` (`GET /signers/{signer_id}/documents/search`).
+- `AuthResource#link_social_login` (`POST /auth/link-social-login`).
+- `SignerResource#upload_signature` accepts an optional `reuse:` flag.
+- An opt-in live integration suite (`spec/integration/`, gated by `ASSINAFY_LIVE=1`)
+  that drives representative workflows against the sandbox and self-cleans.
+- A `.github/dependabot.yml` (bundler + github-actions) so dependency advisories are
+  caught automatically.
+
+### Fixed
+
+- `SignerResource#accept_terms` and `#verify_email` now send `signer-access-code` as
+  the documented query parameter (the `signerAccessCode` security scheme is `in: query`),
+  consistent with every other signer-authenticated endpoint. Previously it was sent
+  only in the request body.
+- `TemplateResource#create` now performs the required `multipart/form-data` file
+  upload. The previous JSON body was rejected by the API (HTTP 400) and never worked.
+  Its signature is now `create(source, options = {}, account_id_override = nil)`.
+- `SignerDocumentResource#download` makes `signer_access_code:` optional — the endpoint
+  is public (`security: []`), so only the document/artifact IDs are required.
+- Document search wrappers send the documented `search` query key; downloads accept the
+  documented `pades` artifact; signer updates preserve `government_id`.
+- `faraday` dependency floor raised to `>= 2.14.3` (CVE-2026-54297, DoS via deeply
+  nested query params).
+
+### Removed
+
+- `WebhookResource#delete`. There is no `DELETE /webhooks/subscriptions` route — it
+  returns HTTP 404 (verified live). Use `#inactivate` to stop deliveries.
+
+### Documentation
+
+- Corrected YARD payloads verified against live responses: `confirm_data` (body is
+  `full_name`/`email`/`government_id`; returns the signer object), `upload_signature`
+  (handles documented no-data responses), `FieldResource#update` (accepts only `name`/`regex`/`is_active`),
+  webhook dispatch shape (ISO-8601 `created_at` + `updated_at`), and template `create`.
+- README updated for the new resources and behaviors, plus live-test instructions.
+
+## 1.4.0
+
+This release is the result of a full audit of the SDK against the live Assinafy
+v1 API (verified end-to-end against the sandbox) and the published documentation
+at <https://api.assinafy.com.br/v1/docs>.
+
+### Added
+
+- `Resources::TemplateResource#delete` (`DELETE /accounts/{account_id}/templates/{template_id}`)
+  and `#download_page` (`GET /accounts/{account_id}/templates/{template_id}/pages/{page_id}/download`)
+  — both verified against the live API.
+- `Support::WebhookVerifier#event_payload`, `#event_object`, and `#event_subject`,
+  matching the real delivery envelope (top-level `payload`/`object`/`subject` keys).
+- `ApiError#error_name` and `ApiError#error_code` expose the API's `name`/`code`
+  error fields; `ApiError.from_response` now also falls back to `name` for the message.
+- YARD `@example` blocks with full request **and** response payloads on every public
+  method, sourced from the live API and the docs.
+- Behavioral coverage: `spec/api_coverage_spec.rb` now also fails CI when a public
+  endpoint wrapper is missing a matrix row, and asserts documented aliases still
+  resolve to their canonical methods. Behavioral WebMock specs were added for the
+  previously untested methods and for `Client#upload_and_request_signatures`.
+
+### Fixed
+
+- `AssignmentResource#reset_expiration` now sends `expires_at` verbatim, so an
+  explicit `nil` is serialized as JSON `null` ("no expiration") instead of being
+  dropped from the body (the field is required by the API). Verified live.
+- `Support::WebhookVerifier#event_data`/`#event_type` corrected to the real envelope:
+  `event_type` reads `event` (the fabricated `type` fallback was removed), and
+  `event_data` is deprecated in favor of `#event_payload`/`#event_object`.
+- `DocumentResource#send_token` validates `recipient`/`channel` before the request.
+- `SignerResource#find_by_email` now paginates through all result pages instead of
+  relying on a single oversized page (the API clamps `per-page` to its own maximum —
+  observed as 50 on the sandbox).
+- `Client#upload_and_request_signatures` raises a clear `ApiError` if a created
+  signer comes back without an ID, rather than building an assignment with `nil` IDs.
+- `TagResource#update` rejects an empty payload or a blank name before issuing a no-op PUT.
+
+### Changed
+
+- **Minimum Ruby is now 3.2** (3.0 and 3.1 are end-of-life). CI tests 3.2, 3.3, 3.4,
+  4.0, and head. `.ruby-version` is committed (3.4.8) and drives the lint/audit/release jobs.
+- `SignerDocumentResource#list` accepts an optional `signer_access_code:` (the endpoint
+  also supports workspace `X-Api-Key` auth); the class auth documentation was corrected.
+- CI gained a `concurrency` group to cancel superseded runs.
+
+## 1.3.1
+
+### Added
+
+- `Client#tags` and `Resources::TagResource` for the documented workspace tag
+  endpoints.
+- Document tag helpers on `Resources::DocumentResource`: `list_tags`,
+  `replace_tags`, `append_tags`, and `detach_tag`.
+
+### Fixed
+
+- Assignment signer payloads now preserve the documented `step` field for
+  sequential signing.
+
+## 1.3.0
+
+### Added
+
+- YARD documentation for every public method on `Client`, `Configuration`,
+  every `Resources::*` class, `Support::WebhookVerifier`, and the SDK's
+  error hierarchy.
+- `spec/api_coverage_spec.rb` — an explicit, version-controlled matrix that
+  asserts every documented endpoint at
+  https://api.assinafy.com.br/v1/docs has a corresponding SDK method.
+
+### Fixed
+
+- `AssignmentResource#sign` now translates snake_case keys (`item_id`,
+  `field_id`, `page_id`, `value`) to the camelCase keys (`itemId`, `fieldId`,
+  `pageId`, `value`) that the `POST /documents/{documentId}/assignments/{assignmentId}`
+  endpoint expects — the only place the API deviates from snake_case.
+  Already-camelCase input is passed through unchanged.
+
+### Changed
+
+- README expanded with one runnable example per resource matching the
+  documented Assinafy v1 surface area.
+
+## 1.2.0
+
+### Changed
+
+- Consolidated HTTP error handling in `BaseResource` behind a single private
+  `request` helper used by `call`, `call_void`, `call_binary`, `call_list`,
+  and `call_optional`.
+- Pagination metadata extraction in `BaseResource` is now driven by a
+  declarative header → key mapping.
+- `Client.from_config` now delegates to `Configuration.from_hash`. A new
+  `Client.from_hash` alias is exposed for symmetry with `Configuration`.
+- `Client#upload_and_request_signatures` no longer duplicates the signer
+  payload normalization logic — it relies on `SignerResource#create`.
+- `NullLogger` now responds to the full Ruby `Logger` severity surface.
+- Minimum Ruby is now 3.0 (matching the CI matrix).
+
+### Removed
+
+- Undocumented `expiration` field from `AssignmentResource.build_payload`
+  — only `expires_at` is documented in the public API.
+
+### Fixed
+
+- Documented `signer-access-code` and pagination handling are now consistent
+  across every resource.
+
+### Release
+
+- Added a tag-triggered release workflow that publishes to both GitHub
+  Packages (`rubygems.pkg.github.com/assinafy`) and RubyGems.org. The verify
+  job blocks publishing when the git tag does not match `Assinafy::VERSION`.

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Assinafy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,463 @@
+# Assinafy Ruby SDK
+
+[![CI](https://github.com/assinafy/ruby-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/assinafy/ruby-sdk/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/assinafy.svg)](https://rubygems.org/gems/assinafy)
+
+Ruby SDK for the [Assinafy API v1](https://api.assinafy.com.br/v1/docs).
+
+The SDK includes a public wrapper for every operation in the current Assinafy v1 [OpenAPI specification](https://api.assinafy.com.br/v1/docs/openapi.json), plus sandbox-live template routes that are not yet listed there. The checked-in [`spec/api_coverage_spec.rb`](spec/api_coverage_spec.rb) verifies that its static route-to-method inventory is unique and points to public SDK methods.
+
+- **Source:** <https://github.com/assinafy/ruby-sdk>
+- **Issues:** <https://github.com/assinafy/ruby-sdk/issues>
+- **API docs:** <https://api.assinafy.com.br/v1/docs>
+
+## Requirements
+
+- Ruby 3.2+ (maintained support: 3.3+; 3.2 is legacy/EOL compatibility)
+- Bundler
+
+## Installation
+
+From RubyGems.org:
+
+```ruby
+gem 'assinafy'
+```
+
+```bash
+bundle install
+```
+
+From GitHub Packages (mirror):
+
+```ruby
+source 'https://rubygems.pkg.github.com/assinafy' do
+  gem 'assinafy'
+end
+```
+
+You'll need a personal access token with `read:packages` scope, configured via:
+
+```bash
+bundle config https://rubygems.pkg.github.com/assinafy USERNAME:TOKEN
+```
+
+## Quick Start
+
+```ruby
+require 'assinafy'
+
+client = Assinafy::Client.new(
+  api_key:    ENV.fetch('ASSINAFY_API_KEY'),
+  account_id: ENV.fetch('ASSINAFY_ACCOUNT_ID')
+)
+
+document = client.documents.upload({ file_path: './contract.pdf' })
+signer   = client.signers.create(full_name: 'Alice Silva', email: 'alice@example.com')
+
+assignment = client.assignments.create(
+  document['id'],
+  method:  'virtual',
+  signers: [{ id: signer['id'] }],
+  message: 'Please sign the attached contract.'
+)
+
+puts assignment['id']
+```
+
+## Configuration
+
+```ruby
+client = Assinafy::Client.new(
+  api_key:        'your-api-key',
+  token:          nil,
+  account_id:     'your-account-id',
+  base_url:       'https://api.assinafy.com.br/v1',
+  webhook_secret: nil,
+  timeout:        30,
+  logger:         Logger.new($stdout)
+)
+```
+
+- `api_key:` sends `X-Api-Key` (preferred).
+- `token:` sends `Authorization: Bearer ...` (legacy session token).
+- A client can also be created with no credentials for authentication and public/signer endpoints.
+- Account-scoped methods document a per-call account override for multi-workspace tenants.
+- Provide a `Logger`-compatible `logger:` to observe upload/assignment/webhook lifecycle messages.
+
+`Client.from_config(hash)` accepts string- or symbol-keyed hashes (e.g. parsed YAML).
+
+## Resources
+
+`Assinafy::Client` exposes twelve accessors — eleven API resources for the current
+OpenAPI operations and sandbox-live template routes, plus the local `webhook_verifier` helper:
+
+| Accessor                    | What it covers                                                 |
+| --------------------------- | -------------------------------------------------------------- |
+| `client.auth`               | Login, social login, password reset, API keys                  |
+| `client.accounts`           | Account CRUD, theme, KPI stats, brand logo                     |
+| `client.users`              | User profile, notification preferences, cross-account KPIs     |
+| `client.documents`          | Upload, list, search, rename, download, delete, verify, tags   |
+| `client.signers`            | Workspace signer CRUD + signer self-service endpoints          |
+| `client.signer_documents`   | Signer-authenticated multi-document operations + search        |
+| `client.assignments`        | List/create/sign/decline/resend/estimate assignments           |
+| `client.templates`          | Template creation (file upload), get, list, update, delete     |
+| `client.tags`               | Workspace tags                                                 |
+| `client.fields`             | Field definitions + validation + type catalog                  |
+| `client.webhooks`           | Subscription, event-type catalog, dispatch history, retries    |
+| `client.webhook_verifier`   | Optional HMAC-SHA256 verifier for signed deliveries            |
+
+### Authentication
+
+```ruby
+client.auth.login(email: 'user@example.com', password: 'secret')
+client.auth.social_login(provider: 'google', token: 'id-token', has_accepted_terms: true)
+client.auth.link_social_login(provider: 'google', token: 'id-token')
+client.auth.create_api_key(password: 'secret')
+client.auth.get_api_key
+client.auth.delete_api_key
+client.auth.change_password(email: 'user@example.com', password: 'old', new_password: 'new')
+client.auth.request_password_reset(email: 'user@example.com')
+client.auth.reset_password(email: 'user@example.com', new_password: 'new', token: 'reset-token')
+```
+
+### Accounts
+
+```ruby
+client.accounts.list                                  # accounts the user can access
+client.accounts.get                                   # the current account (or pass an id)
+client.accounts.create(name: 'Acme Inc.')
+client.accounts.update({ name: 'Acme Renamed' })
+client.accounts.delete(force: true, account_id_override: 'account-id')
+client.accounts.theme                                 # { account_name, primary_color, secondary_color, logo }
+client.accounts.stats(granularity: 'monthly', month: '2026-06')  # account KPI rows
+client.accounts.upload_logo({ file_path: './logo.png' })
+client.accounts.download_logo                          # raw bytes; raises ApiError on HTTP 404 when unset
+client.accounts.delete_logo
+```
+
+### Users
+
+```ruby
+client.users.me # OpenAPI: AuthUser; some sandboxes: { user:, accounts: }; data is passed through
+client.users.stats(granularity: 'monthly')            # cross-account KPI rows
+client.users.notification_preferences                 # returns all nine owner-email preferences
+client.users.update_notification_preferences(SignerDeclined: false) # partial request; returns all nine
+```
+
+Both stats methods return rows with `period`, `documents_uploaded`, `documents_sent`,
+`signature_requests`, `signature_requests_email`, `signature_requests_whatsapp`,
+`signature_requests_viewed`, `signature_requests_completed`, and `documents_certified`.
+
+### Documents
+
+```ruby
+client.documents.statuses                                    # GET /documents/statuses
+client.documents.list(page: 1, per_page: 20, status: 'pending_signature')
+client.documents.search('contract')                          # lightweight GET .../documents/search
+client.documents.upload({ file_path: './contract.pdf' }, name: 'Contract v1')
+client.documents.upload({ buffer: pdf_bytes, file_name: 'contract.pdf' })
+client.documents.rename('document-id', 'renamed.pdf')        # PATCH /documents/{id}
+client.documents.get('document-id')                          # alias of .details
+client.documents.wait_until_ready('document-id', max_wait_seconds: 60)
+client.documents.activities('document-id')
+client.documents.thumbnail('document-id')                    # binary PNG/JPEG
+client.documents.download('document-id', 'certificated')     # binary PDF
+client.documents.download('document-id', 'pades')            # signed PAdES artifact
+client.documents.download_page('document-id', 'page-id')
+client.documents.delete('document-id')
+client.documents.verify('signature-hash')
+client.documents.public_info('document-id')
+client.documents.send_token('document-id') # current OpenAPI also permits no body
+client.documents.send_token('document-id', email: 'alice@example.com') # current OpenAPI body
+# Current sandbox deployment: recipient: 'alice@example.com', channel: 'email'
+client.documents.list_tags('document-id')
+client.documents.replace_tags('document-id', ['tag-id-1', 'tag-id-2'])
+client.documents.append_tags('document-id', ['tag-id-3'])
+# The current sandbox also accepts existing tag names in these arrays.
+client.documents.detach_tag('document-id', 'tag-id')
+
+# Template-driven creation
+client.documents.create_from_template(
+  'template-id',
+  [{ role_id: 'role', id: 'signer-id', verification_method: 'Email', notification_methods: ['Email'] }],
+  { name: 'Contract', message: 'Please sign', expires_at: '2026-12-31T23:59:00Z' }
+)
+client.documents.estimate_cost_from_template(
+  'template-id',
+  [{ role_id: 'role', id: 'signer-id', verification_method: 'Whatsapp' }]
+)
+
+# Convenience: signing progress derived from the embedded assignment summary
+client.documents.fully_signed?('document-id')
+client.documents.signing_progress('document-id')
+# => { signed: 1, total: 2, pending: 1, percentage: 50.0 }
+```
+
+### Signers (workspace CRUD)
+
+```ruby
+client.signers.create(full_name: 'Alice Silva', email: 'alice@example.com')
+client.signers.create(full_name: 'Bob Costa',  phone: '+5548999990000') # phone -> whatsapp_phone_number
+client.signers.get('signer-id')
+client.signers.list(search: 'alice', per_page: 50)  # returns { data:, meta: }
+client.signers.update('signer-id', full_name: 'Alice S.', government_id: '00000000000')
+client.signers.delete('signer-id')
+
+# Convenience: case-insensitive lookup with built-in 404 handling
+client.signers.find_by_email('alice@example.com')
+```
+
+### Signers (self-service, signer-access-code)
+
+```ruby
+client.signers.self_data(signer_access_code: 'code') # includes has_signature, has_initial, is_signature_reusable
+client.signers.accept_terms(signer_access_code: 'code')
+client.signers.verify_email(verification_code: '123456', signer_access_code: 'code')
+client.signers.confirm_data('document-id', { full_name: 'Alice Silva', email: 'alice@example.com', government_id: '00000000000' }, signer_access_code: 'code')
+client.signers.upload_signature(png_bytes, signer_access_code: 'code', type: 'signature', content_type: 'image/png')
+# => nil for the documented no-data envelope; some deployments return []
+client.signers.download_signature(signer_access_code: 'code', type: 'signature')
+```
+
+### Assignments
+
+```ruby
+# Virtual (no positioned fields)
+client.assignments.create(
+  'document-id',
+  method:         'virtual',
+  signers:        [{ id: 'signer-1', verification_method: 'Email', notification_methods: ['Email'], step: 1 }],
+  message:        'Please sign',
+  expires_at:     '2026-12-31T23:59:00Z',
+  copy_receivers: ['cc-signer-id']
+)
+
+# Collect (positioned fields)
+client.assignments.create(
+  'document-id',
+  method:  'collect',
+  signers: [{ id: 'signer-1' }],
+  entries: [{ page_id: 'page-id', fields: [{ signer_id: 'signer-1', field_id: 'field-id',
+                                             display_settings: { left: 100, top: 100, width: 240,
+                                                                 height: 48, fontSize: 16 } }] }]
+)
+
+client.assignments.list                                       # GET /assignments (scoped to the account)
+client.assignments.estimate_cost('document-id', signers: [{ verification_method: 'Whatsapp' }])
+client.assignments.reset_expiration('document-id', 'assignment-id', '2026-12-31T23:59:00Z')
+client.assignments.reset_expiration('document-id', 'assignment-id', nil) # clears the expiry
+client.assignments.resend_notification('document-id', 'assignment-id', 'signer-id')
+client.assignments.estimate_resend_cost('document-id', 'assignment-id', 'signer-id')
+client.assignments.whatsapp_notifications('document-id', 'assignment-id')
+
+# Signer perspective (signer-access-code authentication)
+client.assignments.signer_document(signer_access_code: 'code', has_accepted_terms: true)
+client.assignments.sign(
+  'document-id',
+  'assignment-id',
+  [{ item_id: 'i1', field_id: 'f1', page_id: 'p1', value: 'Alice' }],
+  signer_access_code: 'code'
+)
+client.assignments.decline('document-id', 'assignment-id', decline_reason: 'Clause 2', signer_access_code: 'code')
+```
+
+> The `sign` request body is the API's camelCase body-key exception. This SDK accepts the snake_case keys (`item_id`, `field_id`, `page_id`, `value`) shown above and maps them to `itemId/fieldId/pageId/value` automatically. CamelCase input is also passed through unchanged. Assignment listing separately uses the live-required `accountId` query parameter.
+
+### Signer documents (multi-document workflows)
+
+```ruby
+client.signer_documents.current('signer-id', signer_access_code: 'code')
+client.signer_documents.list('signer-id', { status: 'pending_signature' }, signer_access_code: 'code')
+client.signer_documents.search('signer-id', 'contract', signer_access_code: 'code')
+client.signer_documents.sign_multiple(%w[doc-1 doc-2], signer_access_code: 'code')
+client.signer_documents.decline_multiple(%w[doc-1 doc-2], decline_reason: 'No', signer_access_code: 'code')
+client.signer_documents.download('signer-id', 'document-id', 'pades') # public: no access code needed
+```
+
+### Templates
+
+```ruby
+client.templates.list(search: 'contract', per_page: 25)
+client.templates.get('template-id')
+client.templates.create({ file_path: './contract.pdf' })   # multipart file upload
+client.templates.create({ buffer: pdf_bytes, file_name: 'contract.pdf' })
+client.templates.update('template-id', name: 'Renamed template')
+client.templates.delete('template-id')
+client.templates.download_page('template-id', 'page-id')   # binary image bytes
+```
+
+> Template endpoints (`get`/`create`/`update`/`delete`/`download_page`) are live-verified against the sandbox but are not part of the current OpenAPI document. `create` requires a source file (`multipart/form-data`); the template name defaults to the uploaded file's name.
+
+### Tags
+
+```ruby
+client.tags.list(search: 'contract')
+client.tags.create(name: 'Contracts', color: 'ff8800')
+client.tags.update('tag-id', name: 'Sales Contracts', color: nil)
+client.tags.delete('tag-id')              # fails with 409 if the tag is in use
+client.tags.delete('tag-id', force: true) # detaches from documents/templates first
+```
+
+### Fields
+
+```ruby
+client.fields.types                                           # GET /field-types
+client.fields.list(include_inactive: true, include_standard: false)
+client.fields.create(type: 'text', name: 'Internal code', regex: '/[A-Z]{3}-[0-9]{4}/')
+client.fields.get('field-id')
+client.fields.update('field-id', name: 'Renamed')
+client.fields.delete('field-id')
+
+# Authenticated as a workspace user
+client.fields.validate('field-id', 'ABC-1234')
+# Or authenticated via signer-access-code
+client.fields.validate('field-id', 'ABC-1234', signer_access_code: 'code')
+client.fields.validate_multiple(
+  [{ field_id: 'a', value: '1' }, { field_id: 'b', value: 'value@example.com' }],
+  signer_access_code: 'code'
+)
+```
+
+### Webhooks
+
+```ruby
+client.webhooks.list_event_types                              # GET /webhooks/event-types
+client.webhooks.get                                           # current subscription (nil on 404)
+client.webhooks.register(
+  url:    'https://example.com/webhooks/assinafy',
+  email:  'ops@example.com',
+  events: %w[document_ready document_prepared signer_signed_document]
+)
+client.webhooks.inactivate                                   # stop deliveries, keep the event set
+
+client.webhooks.list_dispatches(delivered: false, per_page: 50)
+client.webhooks.retry_dispatch('dispatch-id')
+```
+
+> To stop deliveries, use `inactivate` (the API has no delete-subscription route).
+
+#### Webhook signature verification
+
+The Assinafy API does not currently document a body-signing scheme for outbound webhook deliveries. The SDK ships an opt-in HMAC-SHA256 verifier you can use when a gateway in front of your receiver is configured to sign payloads with a shared secret:
+
+```ruby
+verifier = Assinafy::Support::WebhookVerifier.new(ENV.fetch('ASSINAFY_WEBHOOK_SECRET'))
+raw_body = request.body.read
+
+# The signature header is one your gateway injects (e.g. Cloudflare / API Gateway).
+# Assinafy v1 does not send a signature header itself.
+if verifier.verify(raw_body, request.headers['X-Webhook-Signature'])
+  event = verifier.extract_event(raw_body)
+  verifier.event_type(event)    # => "assignment_created"  (the top-level `event`)
+  verifier.event_payload(event) # => event-specific params, or nil
+  verifier.event_object(event)  # => the entity acted on, e.g. the document
+  verifier.event_subject(event) # => the actor, e.g. the user
+end
+```
+
+If no `webhook_secret` is configured, `verify` always returns `false` — safe-by-default.
+
+## Responses
+
+Most JSON successes use a `{ "status": ..., "message": ..., "data": ... }` envelope. The SDK
+returns the `data` payload (a Hash for single resources, an Array for collection bodies). For
+documented no-data envelopes containing only `status`/`message`, it returns `nil`; deployed API
+versions that add `data` are passed through. Binary endpoints (`download`, `thumbnail`,
+`download_page`, `download_signature`) return raw bytes as an ASCII-8BIT `String`, and
+delete-style endpoints return `nil`.
+
+Errors surface the envelope/framework error body through `Assinafy::ApiError`:
+
+```ruby
+begin
+  client.documents.details('missing-id')
+rescue Assinafy::ApiError => e
+  e.status_code   # => 404
+  e.message       # => "Documento não encontrado."
+  e.error_name    # => nil (or "Not Found" for framework errors)
+  e.error_code    # => nil (or an integer code)
+  e.response_data # => the raw parsed body
+end
+```
+
+Resource YARD documentation includes request/response examples and calls out known differences
+between the current OpenAPI document and the deployed sandbox.
+
+## Pagination
+
+Most `*.list*` methods return `{ data: [...], meta: { ... } }` when the API includes pagination
+headers. Ruby-style `per_page:` is transparently converted to the documented `per-page` query
+parameter (values above the API's maximum are clamped server-side; the sandbox caps it at 50).
+A few endpoints (e.g. `fields.list`) do not paginate and return `meta: nil`.
+
+```ruby
+result = client.documents.list(page: 2, per_page: 25)
+result[:data] # => Array<Hash>
+result[:meta] # => { current_page: 2, per_page: 25, total: 138, last_page: 6 }
+```
+
+## High-level workflow helper
+
+`Client#upload_and_request_signatures` bundles upload + signer creation + virtual assignment into a single call:
+
+```ruby
+result = client.upload_and_request_signatures(
+  source:  { file_path: './contract.pdf' },
+  signers: [
+    { full_name: 'Alice Silva', email: 'alice@example.com' },
+    { full_name: 'Bob Costa',   whatsapp_phone_number: '+5548999990000' }
+  ],
+  message:    'Please sign.',
+  expires_at: '2026-12-31T23:59:00Z'
+)
+
+puts result[:document]['id']
+puts result[:assignment]['id']
+result[:signer_ids] # => ['<sid-1>', '<sid-2>']
+```
+
+## Errors
+
+The SDK raises one of:
+
+- `Assinafy::ValidationError` — caller-side input invalid (missing IDs, bad email, etc.).
+- `Assinafy::ApiError` — the API returned a non-2xx status. Includes `status_code` and `response_data`.
+- `Assinafy::NetworkError` — Faraday connection error or timeout.
+- `Assinafy::Error` — base class; other unexpected errors get wrapped here with the operation label.
+
+All inherit a `#context` Hash with debugging metadata.
+
+## Tests
+
+```bash
+bundle exec rake spec               # 200+ RSpec examples, including a coverage matrix
+bundle exec rubocop                 # Linting
+bundle exec bundler-audit check     # Dependency CVEs
+```
+
+The coverage spec checks the committed route-to-method matrix for duplicate operations or wrappers, missing public methods, aliases that drift, and unmapped resource methods. It does not download or compare the [OpenAPI document](https://api.assinafy.com.br/v1/docs/openapi.json) during the test run; update the matrix deliberately when the remote contract changes.
+
+### Live integration tests
+
+The suite in [`spec/integration/`](spec/integration/live_sandbox_spec.rb) exercises representative workflows across every resource against the real sandbox. It is not an exhaustive operation-by-operation contract check: OTP- or feature-gated routes may be skipped, and sandbox rollout can lag the current OpenAPI document. The suite is excluded from the default run and only executes when `ASSINAFY_LIVE=1` is set with credentials:
+
+```bash
+ASSINAFY_LIVE=1 \
+ASSINAFY_API_KEY=... \
+ASSINAFY_ACCOUNT_ID=... \
+ASSINAFY_TEST_EMAIL=recipient1@example.com \
+ASSINAFY_TEST_EMAIL2=recipient2@example.com \
+ASSINAFY_BASE_URL=https://sandbox.assinafy.com.br/v1 \
+bundle exec rspec spec/integration
+```
+
+> These tests create and clean up real resources and, for the assignment flow, send real signature-request emails to the addresses in `ASSINAFY_TEST_EMAIL` / `ASSINAFY_TEST_EMAIL2`.
+
+## Contributing
+
+Pull requests and issues are welcome at <https://github.com/assinafy/ruby-sdk>.
+
+## License
+
+MIT. See [LICENSE](LICENSE).