conexa 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ff60656e2731455f658e616416581ede3b7a062e184097f756bcaaca9b523d4
-  data.tar.gz: d3c3a28eb846199bfebfbe963b160af18baab1be9fcfeee2382466a8916c145a
+  metadata.gz: af7a51117e4a311ae46b22248f416838e385336138f60d80c741aa671f47c4fe
+  data.tar.gz: 44aefe94b1b0fccf3b186be4377308bb6fe16e734d6c7c3fbd8adf7e5568cdc9
 SHA512:
-  metadata.gz: 3108d62cff165810c56ae8e5ba738b54ebfa223995617cc7099abebd6511db45a1bab061f7c99df229512ef3004da6d05a0cab623e9662bed464606b9322a1dd
-  data.tar.gz: 1c15d0d6ed78d606e5cfb5a40b56399ab05dacaf8b28bd6562c12ec6f1cae40a87bf3d00e2f09140de061ab36a411eefd63cc2361ae3208907241ec51c23f89e
+  metadata.gz: 52c72131519a01ee69239ac6f63b2f36f4f9f3252ec9d423ce74bd80096ae9e7d25b4eb229dae27a9ad7dac94883cd2b6a3c72db91e9f41cdf68db590a7d7db7
+  data.tar.gz: e85125857aa04e1ec23391063f7a93edaccadfde8dc726ff895fe50ce09dc19b9cd84d846d4ddd5a70046edfec8055c604dd14d64ec12b5d6dc56a0ffff85114

data/CHANGELOG.md

@@ -7,6 +7,63 @@ 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**:
@@ -338,7 +395,8 @@ published documentation, and is now enforced by
 - Charge with settle and PIX methods
 - Pagination support
 
-[Unreleased]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.2.0...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

data/README.md

@@ -44,7 +44,7 @@ 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: 'pending')   # fine
+Conexa::Charge.all(status: 'unpaid')   # fine
 Conexa::Charge.settle(789)              # raises Conexa::ReadOnlyError
 ```
 
@@ -272,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

@@ -49,7 +49,7 @@ confiar na própria atenção.
 ```ruby
 Conexa.configure { |config| config.read_only = true }
 
-Conexa::Charge.all(status: 'pending')   # ok
+Conexa::Charge.all(status: 'unpaid')   # ok
 Conexa::Charge.settle(789)              # levanta Conexa::ReadOnlyError
 ```
 
@@ -200,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)
@@ -528,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

@@ -75,7 +75,7 @@ else warns and is treated as off.
 Conexa.configure { |c| c.read_only = true }   # or CONEXA_READ_ONLY=1
 
 Conexa.read_only do                            # block-scoped, thread-local
-  Conexa::Charge.all(status: 'pending')
+  Conexa::Charge.all(status: 'unpaid')
 end
 ```
 
@@ -339,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],
@@ -396,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
@@ -419,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'
 )
@@ -486,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
@@ -1250,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/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

data/lib/conexa/model.rb

@@ -35,6 +35,8 @@ module Conexa
   # instead of "recurring_sale_id". Explicit declaration ensures correctness.
   #
   class Model < ConexaObject
+    extend Deprecatable
+
     def create
       created = Conexa::Request.post(self.class.show_url, params: to_hash).call(class_name)
 
@@ -227,10 +229,11 @@ module Conexa
             raise RequestError, "size must be a positive integer"
           end
 
-          warn "DEPRECATION WARNING: page/size foi substituído por limit/offset e será " \
-               "removido em conexa 0.3.0. A API v2 valida `page` e depois o ignora, " \
-               "devolvendo sempre a primeira página; os valores foram convertidos para " \
-               "limit=#{size}, offset=#{(page - 1) * size}."
+          deprecate(:page_size,
+                    "page/size foi substituído por limit/offset e será removido em " \
+                    "conexa 0.3.0. A API v2 valida `page` e depois o ignora, devolvendo " \
+                    "sempre a primeira página; os valores são convertidos para " \
+                    "limit=size, offset=(page-1)*size.")
 
           params[:limit]  = size
           params[:offset] = (page - 1) * size

data/lib/conexa/resources/charge.rb

@@ -29,22 +29,64 @@ module Conexa
   class Charge < Model
     primary_key_attribute :charge_id
 
-    # Check if charge is paid
+    # The values `status` can take on a charge, per the collection's field table
+    # for `GET /charge/:id`.
+    #
+    # **`excluded` is here but not in {FILTERABLE_STATUSES}.** The two lists are
+    # not the same thing: a charge can hold a status you cannot query by. This
+    # constant shipped with nine values in 0.2.1 because it was built from the
+    # filter's rejection message rather than from the field table.
+    STATUSES = %w[unpaid paid negotiated generatedByNegotiation cancelled
+                  denied thirdPartyCompany protested juridical excluded].freeze
+
+    # What `GET /charges?status=` accepts. The API names them in the 400 it
+    # returns for an unrecognised value, so this list is the API's own:
+    #
+    #   status=zzz -> 400 "Status is not on the list (unpaid, negotiated,
+    #                 generatedByNegotiation, cancelled, paid, denied,
+    #                 thirdPartyCompany, protested, juridical)"
+    #
+    # `pending` and `overdue` are in neither list, which is why the predicates
+    # built on them never matched.
+    FILTERABLE_STATUSES = (STATUSES - %w[excluded]).freeze
+
     # @return [Boolean]
     def paid?
       status == 'paid'
     end
 
-    # Check if charge is pending
+    # Is this charge still open?
     # @return [Boolean]
-    def pending?
-      status == 'pending'
+    def unpaid?
+      status == 'unpaid'
     end
 
-    # Check if charge is overdue
     # @return [Boolean]
+    def cancelled?
+      status == 'cancelled'
+    end
+
+    # @deprecated The API has no `pending` status; the open state is `unpaid`.
+    #   This alias only exists so callers written against the old, never-matching
+    #   predicate keep working while they migrate.
+    # @return [Boolean]
+    def pending?
+      self.class.deprecate(:pending?,
+                           "`Charge#pending?` foi renomeado para `unpaid?` em conexa 0.2.1 — " \
+                           "a API v2 não tem status `pending`, o estado em aberto chama-se " \
+                           "`unpaid`. O alias será removido em 0.3.0.")
+      unpaid?
+    end
+
+    # @deprecated The API has no `overdue` status. An overdue charge is `unpaid`
+    #   with a `due_date` in the past; compare the date yourself.
+    # @return [Boolean] always false
     def overdue?
-      status == 'overdue'
+      self.class.deprecate(:overdue?,
+                           "`Charge#overdue?` sempre devolveu false — a API v2 não tem status " \
+                           "`overdue`. Use `unpaid?` e compare `due_date`. O método será " \
+                           "removido em 0.3.0.")
+      false
     end
 
     # Settle (pay) this charge

data/lib/conexa/resources/contract.rb

@@ -60,38 +60,81 @@ module Conexa
   # @example End a contract
   #   Conexa::Contract.set_end_date(456, date: '2026-12-31')
   #
+  # == Attributes
+  #
+  # Checked against a live response, not only the collection — which omits
+  # +isActive+, +extraFields+ and +firstDueDate+ from its `GET /contract/:id`
+  # examples even though the API returns them.
+  #
+  # **There is no +status+ field on a contract.** +is_active+ is how you tell an
+  # open contract from a closed one.
+  #
   # @!attribute [r] contract_id
   #   @return [Integer] Contract ID (also accessible as #id)
   # @!attribute [r] customer_id
   #   @return [Integer] Customer ID
   # @!attribute [r] plan_id
   #   @return [Integer, nil] Plan ID
-  # @!attribute [r] status
-  #   @return [String] Status: active, ended, cancelled
+  # @!attribute [r] is_active
+  #   @return [Boolean] whether the contract is open
   # @!attribute [r] start_date
   #   @return [String] Start date
   # @!attribute [r] end_date
-  #   @return [String, nil] End date
-  # @!attribute [r] payment_day
-  #   @return [Integer] Payment day (1-28)
-  # @!attribute [r] value
-  #   @return [Float] Contract value
-  # @!attribute [r] billing_day
-  #   @return [Integer] Billing day
+  #   @return [String, nil] closing date. May be in the future on an **active**
+  #     contract — a scheduled close is not a closed contract.
+  # @!attribute [r] end_reason_id
+  #   @return [Integer, nil] closing-reason id
+  # @!attribute [r] due_day
+  #   @return [Integer] day of the month the contract falls due
+  # @!attribute [r] first_due_date
+  #   @return [String, nil] due date of the first instalment
+  # @!attribute [r] amount
+  #   @return [Float] contract value
+  # @!attribute [r] payment_frequency
+  #   @return [String] monthly, bimonthly, quarterly, semester or yearly
+  # @!attribute [r] date_sales_generation
+  #   @return [String, nil] when sales are generated from the contract
+  # @!attribute [r] cost_center_id
+  #   @return [Integer, nil] cost centre — present on read, rejected on create
+  # @!attribute [r] seller_id
+  #   @return [Integer, nil] seller (user) id
+  # @!attribute [r] contract_summary
+  #   @return [String, nil] short description
+  # @!attribute [r] fidelity_date
+  #   @return [String, nil] loyalty date
+  # @!attribute [r] had_prorata
+  #   @return [Boolean] whether pro rata was applied
   #
   class Contract < Model
     primary_key_attribute :contract_id
 
-    # Check if contract is active
-    # @return [Boolean]
+    # Is this contract open?
+    #
+    # Reads +is_active+, which is what the API sends. It used to compare a
+    # +status+ field that contracts have never had, so it answered +false+ for an
+    # active contract — the answer that makes a caller create a second one.
+    #
+    # Deliberately not derived from +end_date+: an active contract can carry a
+    # future closing date, so a present +end_date+ does not mean closed.
+    #
+    # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
+    # through `!`, so `!active?` reads an *unknown* contract as closed — the
+    # same "treat unknown as inactive" that this fix exists to remove. `ended?`
+    # preserves the nil.
+    #
+    # @return [Boolean, nil] nil when the response did not carry +is_active+,
+    #   rather than a guess
     def active?
-      status == 'active'
+      value = is_active
+      value.nil? ? nil : !!value
     end
 
-    # Check if contract is cancelled/ended
-    # @return [Boolean]
+    # Is this contract closed?
+    # @see #active?
+    # @return [Boolean, nil] nil when the response did not carry +is_active+
     def ended?
-      status == 'ended' || status == 'cancelled'
+      value = active?
+      value.nil? ? nil : !value
     end
 
     # Set this contract's end date — closing it, or amending an existing closure.

data/lib/conexa/util.rb

@@ -68,10 +68,7 @@ module Conexa
         legacy   = [params.delete(:end_date), params.delete("end_date")].compact.first
         explicit = [params.delete(:date), params.delete("date")].compact.first
 
-        if legacy
-          warn "DEPRECATION WARNING: `end_date:` foi renomeado para `date:` em conexa 0.2.0 " \
-               "(a API v2 rejeita `endDate`). O alias será removido em 0.3.0."
-        end
+        warn_end_date_renamed if legacy
 
         # An explicit date wins; a key present with a nil value is not one.
         date = explicit || legacy
@@ -84,6 +81,12 @@ module Conexa
       end
 
 
+      def warn_end_date_renamed
+        Deprecation.warn_once(:end_date_param,
+                              "`end_date:` foi renomeado para `date:` em conexa 0.2.0 " \
+                              "(a API v2 rejeita `endDate`). O alias será removido em 0.3.0.")
+      end
+
       # Convert a payload's keys to the camelCase the API expects, all the way
       # down. Arrays of objects matter as much as nested hashes: ten documented
       # endpoints take them (complementaryServices, productQuotas, devices,

data/lib/conexa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Conexa
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/conexa.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "conexa/version"
+# No dependencies of its own, and Model extends it at load time.
+require_relative "conexa/deprecation"
 require_relative "conexa/request"
 require_relative "conexa/object"
 require_relative "conexa/model"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: conexa
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Guilherme Gazzinelli
@@ -109,6 +109,7 @@ files:
 - lib/conexa.rb
 - lib/conexa/configuration.rb
 - lib/conexa/core_ext.rb
+- lib/conexa/deprecation.rb
 - lib/conexa/errors.rb
 - lib/conexa/generators/install_generator.rb
 - lib/conexa/model.rb