conexa 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c71329999c6d13c4e935ef1e37a8eca6df5811c44d0326184cc1676d31fb199b
-  data.tar.gz: c6f6946375a05712ed7d952a4314738e86a2429bf3a249e269d2fd40b254c11f
+  metadata.gz: af7a51117e4a311ae46b22248f416838e385336138f60d80c741aa671f47c4fe
+  data.tar.gz: 44aefe94b1b0fccf3b186be4377308bb6fe16e734d6c7c3fbd8adf7e5568cdc9
 SHA512:
-  metadata.gz: 13fc7859937cd156cd8ae68b78d6c303b62460d4f6e682f270f58927e87c8a99e29e7d43a4814318b53ed5c5e20ce5e0ea3892d46db8d4d08147e9aea79a690e
-  data.tar.gz: c1ae89758b0cea23df6c5f5cc16895c060baef04da9a31fefd58eb7ac9c7ba1b1483dfc44b81c00ddfb592cada2e34cace170237e5f298b3ea8b3217572bd1c9
+  metadata.gz: 52c72131519a01ee69239ac6f63b2f36f4f9f3252ec9d423ce74bd80096ae9e7d25b4eb229dae27a9ad7dac94883cd2b6a3c72db91e9f41cdf68db590a7d7db7
+  data.tar.gz: e85125857aa04e1ec23391063f7a93edaccadfde8dc726ff895fe50ce09dc19b9cd84d846d4ddd5a70046edfec8055c604dd14d64ec12b5d6dc56a0ffff85114

data/CHANGELOG.md

@@ -7,6 +7,268 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-08-13
+
+Found validating 0.2.1 against a live tenant before publishing, and by reviewing
+the same release. Folded in rather than shipped separately — 0.2.1 was never
+published.
+
+### Fixed — found validating and reviewing
+- **`Charge::STATUSES` was the filter list, not the field list.** It shipped with
+  nine values, built from the 400 the API returns for an unrecognised filter. The
+  field itself can also hold `excluded`, which `?status=` does not accept — two
+  different lists, now `STATUSES` (10) and `FILTERABLE_STATUSES` (9).
+- **`REFERENCE.md` still documented the pre-0.2.1 behaviour** — `contract.status`,
+  `charge.pending?`, and `status` listed as `active, ended, cancelled` /
+  `pending, paid, overdue`. A reader following it wrote code against fields and
+  values that do not exist. Every doc example filtering charges by
+  `status: "pending"` was also rejected by the API; corrected to `unpaid`.
+- **Deprecations warn once per process.** `charges.select(&:pending?)` over one
+  page emitted a hundred identical lines, which is how a warning stops being read.
+- `HANDOFF-0.2.1` §2 offered `Charge.settle(1)` to verify read-only mode. That
+  calls `find` first — a GET the guard allows — so it answered `NotFound` and
+  never reached the guard; and making it work would require pointing a real
+  settlement at a real charge to test the brake. Replaced with a transport call.
+  (#26)
+
+### Changed
+- `Contract#active?` documents that `ended?` is the safe negation: `!active?`
+  reads an unknown contract as closed, because Ruby cannot tell `nil` from
+  `false` through `!`.
+
+### Fixed — the original issue #23
+- **`Contract#active?` and `#ended?` read `is_active`.** They compared a `status`
+  field contracts have never had, so `active?` answered `false` for an active
+  contract — the answer that biases a caller toward creating a second one. Both
+  return `nil` rather than a guess when the response did not carry `is_active`.
+  Deliberately not derived from `end_date`: an active contract can carry a future
+  closing date, so a present `end_date` does not mean closed. (#23)
+- **`Charge#pending?` and `#overdue?` never matched anything.** API v2 has no
+  `pending` or `overdue` status — it rejects both and names the real set in the
+  400. The open state is **`unpaid`**. `#unpaid?` and `#cancelled?` are the
+  replacements; `pending?` stays as a deprecated alias, and `overdue?` warns and
+  returns false, since an overdue charge is `unpaid` with a `due_date` in the
+  past. `Charge::STATUSES` records the enum the API named.
+- **`Contract`'s attribute documentation** described `status`, `payment_day`,
+  `value` and `billing_day`. None of the four exists. Replaced with the real
+  fields, verified against a live response rather than the collection alone.
+
+`Sale`'s predicates were checked and left alone — `billed`, `paid` and
+`notBilled` are all real values.
+
+### Added
+- `PostmanCollection.response_fields`, and specs asserting that the attributes
+  the predicates depend on appear in a documented response. The contract layer
+  compared verbs and paths only, which is exactly how a predicate could read a
+  field that has never existed. It is deliberately a union across examples and
+  never an exact set: the collection under-documents responses, so an exact-match
+  check would report real fields as missing.
+
+## [0.2.0] - 2026-08-11
+
+Aligns the gem with the published API v2 contract. **0.1.1 is broken**:
+`Charge.settle` and `Contract.end_contract` 404 against a live tenant, and a
+successful write that answers with an empty body raises `NoMethodError` after
+the operation has already taken effect — in a billing integration that invites a
+retry. Upgrading is strongly recommended.
+
+Every fix below was verified against `docs/postman-collection.json`, Conexa's own
+published documentation, and is now enforced by
+`spec/contract/api_contract_spec.rb`.
+
+### Fixed
+- **Empty response bodies no longer raise, anywhere.** `Request#run` returns `{}`
+  for an empty, whitespace or `null` body at any status. With the Oj adapter
+  `MultiJson.decode("")` returns `nil` without raising, so the previous
+  `rescue MultiJson::ParseError` / `204` guard never fired — even a documented
+  `204` success (`PATCH /charge/settle/:id`) raised `NoMethodError`, which is not
+  a `Conexa::ConexaError` and escaped `rescue Conexa::ConexaError`.
+
+  `ConexaObject#update` treats anything carrying no attributes as "nothing to
+  merge" — `nil`, `{}`, and the arrays and scalars `Request#run` also produces —
+  and `Model#create` does the same. Fixing `Request#run` alone was not enough:
+  `Model#save` and `#destroy` fed the result straight into `update`, so **every**
+  resource's generic CRUD still raised `NoMethodError` on a documented `204`
+  (`DELETE /sale/:id` among them). Only the three action methods were safe, and
+  only because they discard their return value.
+- **A write answering `200 {}` no longer wipes the object.** `update` removes
+  every attribute absent from the incoming hash, which is right for a full
+  refresh and destructive for an empty write response — it cleared the whole
+  object, primary key included, and reported success.
+- **`Model#save` guards a blank id**, as `#destroy` already did. Without it an
+  id-less object issued `PATCH /customer/` instead of failing fast.
+- **`Result#next_page` raises a `Conexa` error** when pagination carries no
+  `limit`, instead of `TypeError` from `nil + Integer`, and survives a
+  non-marshallable filter in the original query.
+- **`Conexa::ValidationError` is usable.** It rendered as the bare string
+  `"Conexa::ValidationError"` and `#to_h` raised `NoMethodError`. It is only
+  reachable for an error body with no `message` key — which no documented
+  response has — but it now reports what actually arrived.
+- **Exception messages read as prose.** The old format appended a dangling
+  `"=> Erros: "` to the 75 documented responses that carry no `errors` array, and
+  dumped Ruby's `#inspect` of an array of hashes for the ones that do. It now
+  uses the same normalisation as `#api_error_messages`:
+  `422 … => It was not possible to process your request — CHARGE_11: Only open charges can be settled.`
+- **Error bodies that are not JSON objects no longer raise `TypeError`.** An
+  array or scalar error body reached `parsed_error['message']` and blew up inside
+  the error handler.
+- **`Request#run` tolerates a top-level array or scalar body.** Defensive: every
+  list endpoint probed on 2026-08-12 used the `{data, pagination}` envelope, so
+  this shape has not been observed in the wild — it removes a crash class rather
+  than fixing a seen failure.
+- **Action endpoints use the documented verb.** `Charge#settle`,
+  `Contract#end_contract` and `RecurringSale#end_recurring_sale` send `PATCH`;
+  `POST` 404s.
+- **`Conexa::Company.all` requests the documented `/companies`.** `Model#url`
+  pluralizes by appending `"s"`, which produced `/companys`. A read-only probe of
+  a live tenant on 2026-08-12 showed the API routes **both** spellings, so this
+  was an undocumented path that worked rather than the 404 first reported — the
+  override stands because an undocumented alias can vanish without notice, but
+  nothing was broken by it.
+- **Nested arrays are camelized.** `Util.camelize_hash` treated an `Array` as a
+  scalar, so snake_case keys inside arrays of objects were sent untouched and
+  rejected. Affects `complementaryServices`, `productQuotas`, `devices`,
+  `extraFields`, `bookingModels`, `visitors` and `costCenters` — ten documented
+  endpoints across seven resources.
+- **`page`/`size` are converted to `limit`/`offset`** instead of being sent. The
+  API validates `page` and then ignores it, always answering `offset: 0`, so a
+  loop driven by `hasNext` never terminated and silently re-yielded the same
+  batch. Non-positive or non-integer values now raise `Conexa::RequestError`.
+- **`Model#id` falls back to `attributes["id"]` again.** `primary_key_attribute`
+  aliased `#id` onto the resource key, making the documented fallback dead code —
+  write endpoints answer with `{"id": N}`, which is what `Model#create` reads.
+- **`ResponseError` no longer raises `NoMethodError` on malformed bodies.** It was
+  handed a `RestClient::Response`, which has no `#message`.
+- **A broken connection raises `Conexa::ConnectionError`** (issue #11). The
+  `rescue RestClient::ServerBrokeConnection` clause was unreachable —
+  `ServerBrokeConnection` subclasses `RestClient::Exception`, so the broader
+  clause listed above it always matched first, then tried to decode a `nil`
+  `http_body` and raised `NoMethodError` from inside the error handler.
+  Connection-level failures are now rescued first: `SocketError`,
+  `ServerBrokeConnection`, `SSLCertificateNotVerified` and
+  `RestClient::Exceptions::Timeout`. A real HTTP 408 stays in the response
+  taxonomy, since `RestClient::RequestTimeout` is a *superclass* of
+  `Exceptions::Timeout`.
+- **An unusable id raises `Conexa::RequestError`, not `URI::InvalidURIError`**
+  (issue #12). `find(" 123 ")` leaked a URI error from inside RestClient, outside
+  the `Conexa::ConexaError` hierarchy. Surrounding whitespace is now stripped, and
+  `Request#full_api_url` validates the URL it builds.
+- **`RecurringSale#end_recurring_sale` sends the documented `date`.** The verb was
+  corrected but the field was not, so `end_date:` still went out as the rejected
+  `endDate`, and its YARD named that field as the example. It now shares
+  `Util.normalize_end_date_param` with `Contract`, and gains a `set_end_date`
+  alias for symmetry.
+- `README.md` configured a non-existent `config.subdomain`; the quick start now
+  runs.
+- `lib/conexa/resources/supplier.rb` shipped as `0600`, breaking `require` on a
+  shared install.
+
+- **`Conexa::CreditCard` is write-only.** API v2 exposes no read for it: `GET
+  /creditCard` answers "Unable to resolve the request" and `GET /creditCard/:id`
+  "unable to find the requested action" — neither is the permission wording the
+  API uses for a resource an account cannot see. `all`/`find`/`find_by` and their
+  aliases now raise `Conexa::RequestError` explaining that, instead of a bare
+  `NotFound` reading as "no such card", and `#create` skips `Model#create`'s
+  re-fetch. The integration spec that asserted those reads worked — against
+  stubs of endpoints that do not exist — was rewritten.
+- **Listings always answer with a `Conexa::Result`.** An empty body yielded `nil`
+  and a bare-array body an `Array`, so `.data`/`.pagination`/`.next_page` failed
+  far from the cause.
+- **`Model#fetch` raises instead of silently keeping stale attributes** when the
+  refresh comes back with no body. The nil-guard that makes an empty *write*
+  response harmless must not make an empty *read* look successful.
+- **`Result#has_next?` returns a boolean**, not `nil`, when there is no
+  pagination at all.
+
+### Added
+- **Read-only mode.** `config.read_only = true`, `CONEXA_READ_ONLY=1`, or a
+  `Conexa.read_only { ... }` block. Any non-`GET` request raises
+  `Conexa::ReadOnlyError` before it leaves the process. Settling a charge moves
+  money and can issue an NF-e, so this is a guard worth having when you only mean
+  to read.
+
+  The exemption for `POST /auth` is matched on the **path**, not on the caller's
+  `auth:` flag — `Request.auth` is public, so keying it off the flag would have
+  let any write opt out of the guard. `CONEXA_READ_ONLY` is consulted at each
+  check rather than captured at configure time, and an unrecognised value warns
+  instead of silently failing open. The block form is fiber-local and does not
+  reach a `Thread` or `Fiber` spawned inside it — documented in the READMEs; use
+  `config.read_only` for concurrent work.
+- **`ResponseError#api_errors`, `#api_error_codes`, `#api_error_messages`,
+  `#api_response`** — normalise the API's two error shapes (`{field, messages}`
+  and `{code, message}`). Consumers that only handled the first rendered
+  business-rule errors as blank strings, which is how
+  `CONTRACT_RECURRING_SALE_10` stayed invisible through eight attempts.
+  `api_error_codes` makes documented codes such as `CHARGE_11` usable as control
+  flow — the way to tell an already-settled charge from a real failure.
+- **`Contract#set_end_date`** (with `end_contract` kept as an alias), taking the
+  documented `date:`, `reason_id:` and `unlink_customer:`. The endpoint both
+  closes a contract and amends its end date, and a future date on a closed
+  contract reopens it.
+- **Contract-level test coverage**: `spec/contract/api_contract_spec.rb` checks
+  every emitted URL and action verb against the vendored collection, with an
+  explicit allowlist and a guard that fails when an endpoint is added without one.
+  `spec/support/request_capture.rb` asserts the request the gem actually emits
+  rather than stubbing the expected one.
+- `verify_partial_doubles = true`.
+- YARD documentation of `POST /contract`'s fields, including the conditional
+  `due_day` rule and the atomic `firstOccurrenceSettleRetroactive` flow.
+
+### Changed
+- **Breaking**: `end_contract` sends the documented `date`; `end_date:` still
+  works as a deprecated alias and will be removed in 0.3.0.
+- **Breaking**: writes that answer with an empty body now return normally instead
+  of raising. Callers treating the exception as a signal must be reviewed.
+- **Breaking**: `page`/`size` no longer reach the wire.
+- Minimum Ruby is now **3.1** (was 2.6, never tested below 3.1). CI covers
+  3.1–3.4.
+- `rest-client` and `multi_json` are version-bounded. `multi_json`'s adapter
+  behaviour is load-bearing — the empty-body defect exists because Oj returns
+  `nil` rather than raising.
+- The gemspec's development dependencies move to bundler's `:test` group, and
+  `debug`/`byebug` to an optional `:development` group, so a native-extension
+  failure in `io-console` can no longer stop `bundle exec rspec`.
+- **The packaged gem is 48 KB, down from 163 KB.** `spec.files` shipped the whole
+  repository — including `docs/postman-collection.json` (1.7 MB) — against 58 KB
+  of library code. It now ships `lib/` and the documentation only.
+- **`Gemfile.lock` is no longer committed**, as is conventional for a gem: a
+  pinned lockfile defeats testing against the range the gemspec allows, and CI
+  had been working around it by deleting the file before `bundle install`.
+- **`rake` passes again.** The default task is `spec` + `rubocop`, and RuboCop's
+  ~2000 pre-existing offences made it fail, which is why CI ran lint with
+  `continue-on-error`. A generated `.rubocop_todo.yml` grandfathers them, so new
+  code is genuinely linted and CI can gate on it.
+- `rake spec:all` runs the suite across every supported Ruby via mise; `rake ci`
+  adds RuboCop. CI uses `bundler-cache: true`.
+- **Releases publish from CI via Trusted Publishing.** Pushing a `v*` tag runs
+  the full gate and then exchanges GitHub's OIDC token for a short-lived,
+  push-scoped RubyGems credential — no API key is stored anywhere. Two gates run
+  first, both aimed at how 0.1.1 went out: the tag must match `Conexa::VERSION`
+  (the `v0.1.1` tag points at code carrying `0.1.0`), and the packaged gem must
+  contain only `lib/` and the documentation.
+
+### Removed
+- **Breaking**: `Conexa::Client`, `Conexa::Authenticator` and
+  `Conexa::TokenManager`. They referenced five `Conexa` module methods that never
+  existed (`credentials`, `secret_key`, `access_key`, `client_id`,
+  `default_client_key`), so any real use raised `NoMethodError`; their specs
+  passed only because they stubbed those methods into being. The `jwt` dependency
+  goes with them — `Conexa::Auth` (the v2 `/auth` resource) is unaffected.
+- **Breaking**: `Conexa::OrderCommon`. Unlike the three above, this one *ran* —
+  it built `/order/:id` and `/order/:id/refund` and issued a real `DELETE`. It is
+  removed because **API v2 documents no `/order` endpoint at all**: nothing in
+  the gem used it, no spec covered it, and it targets a surface that no longer
+  exists. Note that its documented backwards-compatible alias never worked:
+  `OrderCommom = self` inside the class body defines
+  `Conexa::OrderCommon::OrderCommom`, not `Conexa::OrderCommom`, so the pre-0.1.0
+  name has raised `NameError` since the rename.
+
+### Testing
+- VCR cassettes recorded against a real tenant are anonymised, and
+  `spec_helper.rb` filters the API token out of new recordings. The
+  `claude_scripts/sanitize_cassettes/` script does the anonymisation in place,
+  keeping the JSON shape so the specs still exercise the same structure.
+
 ## [0.1.1] - 2026-03-31
 
 ### Added
@@ -133,7 +395,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Charge with settle and PIX methods
 - Pagination support
 
-[Unreleased]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.0.9...v0.1.0
 [0.0.9]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.0.8...v0.0.9

data/README.md

@@ -25,8 +25,8 @@ gem install conexa
 
 ```ruby
 Conexa.configure do |config|
-  config.subdomain = 'YOUR_SUBDOMAIN'  # your-company.conexa.app
-  config.api_token = 'YOUR_API_TOKEN'  # Application Token from Conexa
+  config.api_host  = 'https://your-company.conexa.app'  # your tenant
+  config.api_token = 'YOUR_API_TOKEN'                   # Application Token from Conexa
 end
 ```
 
@@ -35,13 +35,45 @@ end
 1. **Application Token** (recommended): Created in Conexa at **Config > Integrações > API / Token**
 2. **Username/Password**: Use the `/auth` endpoint to get a JWT token
 
+### Read-only mode
+
+This gem talks to a billing system: settling a charge moves money and can issue
+an NF-e. When you only mean to read — auditing, reporting, investigating — turn
+writing off and let the gem refuse instead of trusting yourself to be careful.
+
+```ruby
+Conexa.configure { |config| config.read_only = true }
+
+Conexa::Charge.all(status: 'unpaid')   # fine
+Conexa::Charge.settle(789)              # raises Conexa::ReadOnlyError
+```
+
+Set `CONEXA_READ_ONLY=1` in the environment to default it on — useful in CI, or
+in any shell where you would rather not discover you were pointed at production.
+
+For a single block, without reconfiguring the client:
+
+```ruby
+Conexa.read_only do
+  report = Conexa::Charge.all(limit: 100)   # anything here is read-only
+end
+```
+
+The guard runs before the request leaves the process, so a blocked call never
+reaches your tenant. `GET` is allowed, and so is `POST /auth` — without it
+read-only mode could not obtain a token.
+
+**The block form is fiber-local.** It does not reach a `Thread` or `Fiber`
+spawned inside it, nor external iteration on an `Enumerator`. For anything
+concurrent use `config.read_only` (or `CONEXA_READ_ONLY`), which is global.
+
 ## Quick Start
 
 ```ruby
 require 'conexa'
 
 Conexa.configure do |config|
-  config.subdomain = 'mycompany'
+  config.api_host  = 'https://mycompany.conexa.app'
   config.api_token = ENV['CONEXA_API_TOKEN']
 end
 
@@ -240,7 +272,7 @@ charge.due_date   # => "2024-02-10"
 # List charges
 charges = Conexa::Charge.all(
   customer_id: [127],
-  status: 'pending',
+  status: 'unpaid',
   due_date_from: '2024-01-01',
   due_date_to: '2024-12-31'
 )

data/README_pt-BR.md

@@ -37,7 +37,41 @@ Conexa.configure do |config|
 end
 ```
 
-Certifique-se de que as variáveis de ambiente `API_TOKEN` e `API_HOST` estejam configuradas com seu token e URL da API Conexa.
+Certifique-se de que as variáveis de ambiente `API_TOKEN` e `API_HOST` estejam configuradas com seu token e URL da API Conexa. O `api_host` é o subdomínio do seu tenant, por exemplo `https://minhaempresa.conexa.app`.
+
+### Modo somente-leitura
+
+Esta gem conversa com um sistema de cobrança: quitar uma cobrança movimenta
+dinheiro e pode emitir NF-e. Quando a intenção é apenas consultar — auditoria,
+relatório, investigação — desligue a escrita e deixe a gem recusar, em vez de
+confiar na própria atenção.
+
+```ruby
+Conexa.configure { |config| config.read_only = true }
+
+Conexa::Charge.all(status: 'unpaid')   # ok
+Conexa::Charge.settle(789)              # levanta Conexa::ReadOnlyError
+```
+
+Defina `CONEXA_READ_ONLY=1` no ambiente para ligar por padrão — útil em CI, ou em
+qualquer shell onde você prefira não descobrir que estava apontando para
+produção.
+
+Para um trecho específico, sem reconfigurar o cliente:
+
+```ruby
+Conexa.read_only do
+  relatorio = Conexa::Charge.all(limit: 100)   # tudo aqui dentro é leitura
+end
+```
+
+A verificação acontece antes de a requisição sair do processo, então uma chamada
+bloqueada nunca chega ao seu tenant. `GET` é permitido, e o `POST /auth` também —
+sem ele o modo leitura não conseguiria obter token.
+
+**O bloco é fiber-local.** Ele não alcança uma `Thread` ou `Fiber` criada lá
+dentro, nem iteração externa de `Enumerator`. Para qualquer coisa concorrente use
+`config.read_only` (ou `CONEXA_READ_ONLY`), que é global.
 
 ## Uso
 
@@ -166,7 +200,7 @@ Conexa::Company.all(
 )
 
 # Filtrar faturas por status
-Conexa::Bill.all(status: "pending", page: 1, size: 20)
+Conexa::Bill.all(status: "unpaid", limit: 20)
 
 # Filtrar vendas
 Conexa::Sale.all(page: 2, size: 6)
@@ -494,7 +528,7 @@ Conexa::Bill.destroy(bill_id)
 ##### Listando Faturas
 
 ```ruby
-faturas = Conexa::Bill.find({ status: 'pending' }, 1, 20)
+faturas = Conexa::Bill.find_by({ status: 'unpaid', limit: 20 })
 ```
 
 #### Cobranças (Charges)

data/REFERENCE.md

@@ -42,8 +42,9 @@ gem install conexa
 
 ```ruby
 Conexa.configure do |config|
-  config.api_host = 'https://api.conexa.com.br'  # or sandbox URL
+  config.api_host  = 'https://mycompany.conexa.app'  # your tenant subdomain
   config.api_token = 'your_api_token_here'
+  config.read_only = false                           # see below
 end
 
 # Rails: use generator
@@ -51,6 +52,33 @@ rails generate conexa:install
 # Creates config/initializers/conexa.rb
 ```
 
+| Setting | Default | Purpose |
+|---------|---------|---------|
+| `api_host` | `''` | Tenant base URL. `/index.php/api/v2` is appended automatically. |
+| `api_token` | `''` | Application Token — Config > Integrações > API / Token. |
+| `read_only` | `ENV['CONEXA_READ_ONLY']` | Refuse every non-GET request. |
+
+### Read-only mode
+
+Any request other than `GET` raises `Conexa::ReadOnlyError` before it leaves the
+process. `POST /auth` stays allowed — matched on the path, not on a caller flag —
+since read-only mode would otherwise be unable to obtain a token.
+
+`Conexa.read_only { }` is fiber-local: it does not reach a `Thread` or `Fiber`
+spawned inside the block. Use `config.read_only` for concurrent work.
+
+`CONEXA_READ_ONLY` is read at each check, so it applies even when set after
+`Conexa.configure`. Recognised: `1/true/yes/on` and `0/false/no/off`; anything
+else warns and is treated as off.
+
+```ruby
+Conexa.configure { |c| c.read_only = true }   # or CONEXA_READ_ONLY=1
+
+Conexa.read_only do                            # block-scoped, thread-local
+  Conexa::Charge.all(status: 'unpaid')
+end
+```
+
 ## Convention: snake_case
 
 This gem follows Ruby/Rails conventions. Use **snake_case** for all parameters - the gem automatically converts to camelCase for the API.
@@ -311,10 +339,18 @@ contract = Conexa::Contract.create_with_products(
 
 # Find contract
 contract = Conexa::Contract.find(456)
-contract.status       # => "active"
+contract.is_active    # => true   (contracts have no `status` field)
 contract.active?      # => true
 contract.ended?       # => false
 
+# An ACTIVE contract may carry a future end_date — a scheduled close is not a
+# close. Do not derive "ended" from end_date.
+contract.end_date     # => "2026-11-30" while still active?
+
+# active?/ended? return nil when the response did not carry is_active, rather
+# than guessing. Prefer ended? over !active?: !nil is true, which would read an
+# unknown contract as closed.
+
 # List contracts
 contracts = Conexa::Contract.all(
   customer_id: [127],
@@ -368,7 +404,9 @@ contract.destroy
 
 **Read-only attributes:**
 - `contract_id` - ID
-- `status` - active, ended, cancelled
+- `is_active` - whether the contract is open (there is **no** `status` field)
+- `end_date` - closing date; may be in the future on an active contract
+- `due_day`, `amount`, `payment_frequency`, `end_reason_id`, `first_due_date`
 
 **Helper methods:**
 - `active?` - Check if active
@@ -391,17 +429,19 @@ charge = Conexa::Charge.create(
 
 # Find charge
 charge = Conexa::Charge.find(789)
-charge.status      # => "pending"
+charge.status      # => "unpaid"
 charge.amount      # => 199.90
 charge.due_date    # => "2024-02-10"
 charge.paid?       # => false
-charge.pending?    # => true
-charge.overdue?    # => false
+charge.unpaid?     # => true    (the open state is `unpaid`, not `pending`)
+charge.cancelled?  # => false
+Conexa::Charge::STATUSES             # every value the field can take
+Conexa::Charge::FILTERABLE_STATUSES  # what ?status= accepts — not the same list
 
 # List charges
 charges = Conexa::Charge.all(
   customer_id: [127],
-  status: 'pending',
+  status: 'unpaid',
   due_date_from: '2024-01-01',
   due_date_to: '2024-01-31'
 )
@@ -458,8 +498,11 @@ Conexa::Charge.cancel(789)
 
 **Helper methods:**
 - `paid?` - Check if paid
-- `pending?` - Check if pending
-- `overdue?` - Check if overdue
+- `unpaid?` - Check if still open
+- `cancelled?` - Check if cancelled
+- `pending?` - **deprecated** alias of `unpaid?`; the API has no `pending`
+- `overdue?` - **deprecated**, always false. The API has no `overdue`: an overdue
+  charge is `unpaid` with a `due_date` in the past, so compare the date yourself
 
 **Special methods:**
 - `settle(params)` / `Charge.settle(id, params)` - Mark as paid
@@ -1222,7 +1265,7 @@ Conexa::Sale.all(status: 'notBilled')
 # Combined
 Conexa::Charge.all(
   customer_id: [127],
-  status: 'pending',
+  status: 'unpaid',
   due_date_from: '2024-01-01',
   page: 1,
   size: 100

data/lib/conexa/configuration.rb

@@ -2,11 +2,57 @@
 
 module Conexa
   class Configuration
-    attr_accessor :api_token, :api_host
+    # @return [String] the Application Token, created in Conexa under
+    #   Config > Integrações > API / Token
+    attr_accessor :api_token
+
+    # @return [String] the tenant base URL, e.g. "https://mycompany.conexa.app"
+    attr_accessor :api_host
+
+    # Set to force read-only mode on or off, overriding the environment.
+    # @return [Boolean]
+    attr_writer :read_only
+
+    # Values that turn read-only mode on via CONEXA_READ_ONLY.
+    TRUTHY = %w[1 true yes on].freeze
+
+    # Values that explicitly turn it off. Anything else is a typo worth warning
+    # about — silently failing open on `CONEXA_READ_ONLY=treu` would leave an
+    # operator believing writes were blocked when they are not.
+    FALSEY = %w[0 false no off].freeze
 
     def initialize
       @api_token = ''
       @api_host = ''
+      @read_only = nil
+    end
+
+    # When true, any request other than GET raises {Conexa::ReadOnlyError} before
+    # reaching the network.
+    #
+    # Read lazily so that CONEXA_READ_ONLY still applies when it is set after
+    # {Conexa.configure} has run — it used to be captured once at initialization,
+    # which made setting it later a silent no-op. An explicit assignment always
+    # wins over the environment.
+    #
+    # @return [Boolean]
+    def read_only
+      return @read_only unless @read_only.nil?
+
+      env_read_only
+    end
+
+    private
+
+    def env_read_only
+      value = ENV["CONEXA_READ_ONLY"].to_s.strip.downcase
+      return false if value.empty?
+      return true  if TRUTHY.include?(value)
+      return false if FALSEY.include?(value)
+
+      warn "Conexa: CONEXA_READ_ONLY=#{value.inspect} não é reconhecido e foi ignorado " \
+           "(modo somente-leitura DESLIGADO). Use um de: #{(TRUTHY + FALSEY).join(", ")}."
+      false
     end
   end
-end
+end

data/lib/conexa/deprecation.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Conexa
+  # Emits each deprecation once per process.
+  #
+  # The warnings exist to be read once and acted on. Emitting per call turns them
+  # into noise a caller learns to filter — `charges.select(&:pending?)` over one
+  # page of results produced a hundred identical lines, which is how a warning
+  # stops being read.
+  module Deprecation
+    @seen  = {}
+    @mutex = Mutex.new
+
+    class << self
+      # @param key [Object] identifies the deprecation, not the call site
+      # @param message [String] what changed and what to do instead
+      # @return [nil]
+      def warn_once(key, message)
+        @mutex.synchronize do
+          return nil if @seen[key]
+
+          @seen[key] = true
+        end
+
+        Kernel.warn("DEPRECATION WARNING: #{message}")
+        nil
+      end
+
+      # Only for tests: lets a spec observe a warning that another example
+      # already consumed.
+      # @api private
+      def reset!
+        @mutex.synchronize { @seen = {} }
+      end
+    end
+  end
+
+  # Mixed into the classes that carry deprecated methods.
+  module Deprecatable
+    def deprecate(key, message)
+      Deprecation.warn_once([self, key], message)
+    end
+  end
+end