conexa 0.1.1 → 0.2.1

data/lib/conexa/errors.rb

@@ -16,40 +16,112 @@ module Conexa
   class RequestError < ConexaError
   end
 
+  # Raised instead of performing a mutating request while Conexa.read_only?.
+  # The request never reaches the network.
+  class ReadOnlyError < ConexaError
+  end
+
   class ResponseError < ConexaError
     attr_reader :request_params, :error
 
-    def initialize(request_params, error, message=nil)
+    # The decoded error body, when the API returned one.
+    # @return [Hash]
+    attr_reader :api_response
+
+    def initialize(request_params, error, message=nil, api_response=nil)
       @request_params, @error = request_params, error
-      msg = @error.message
+      @api_response = api_response.is_a?(Hash) ? api_response : {}
+      msg = describe_error(error)
       msg +=  " => " + message if message
       super msg
     end
+
+    # The API's errors, normalised across its two shapes.
+    #
+    # Field validation answers `{"field": …, "messages": [...]}`; business rules
+    # answer `{"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.
+    #
+    # @return [Array<Hash{Symbol=>String,nil}>] entries of {field:, code:, message:}
+    def api_errors
+      Array(api_response["errors"]).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        { field:   entry["field"],
+          code:    entry["code"],
+          message: entry["message"] || Array(entry["messages"]).join("; ") }
+      end
+    end
+
+    # Documented business-rule codes, e.g. "CHARGE_11" or
+    # "CONTRACT_RECURRING_SALE_10". These are what a caller branches on — for
+    # instance to tell an already-settled charge from a real settlement failure.
+    #
+    # @return [Array<String>]
+    def api_error_codes
+      api_errors.filter_map { |entry| entry[:code] }
+    end
+
+    # One readable line per error, whichever shape it arrived in.
+    # @return [Array<String>]
+    def api_error_messages
+      api_errors.map do |entry|
+        label = entry[:field] || entry[:code]
+        label ? "#{label}: #{entry[:message]}" : entry[:message]
+      end
+    end
+
+    private
+
+    # `error` is usually a RestClient::Exception, but the malformed-body path
+    # hands us a RestClient::Response, which has no #message — that used to raise
+    # NoMethodError from inside the error constructor itself.
+    def describe_error(error)
+      return error.message if error.respond_to?(:message) && error.message
+      return "HTTP #{error.code}: #{error.body.to_s[0, 200]}" if error.respond_to?(:code)
+
+      error.to_s
+    end
   end
 
   class NotFound < ResponseError
     attr_reader :response
     def initialize(response, request_params, error)
       @response = response
-      super request_params, error, response&.dig('message')
+      super request_params, error, response&.dig('message'), response
     end
   end
 
+  # Raised for an error body with no `message` key.
+  #
+  # Every error response the published collection documents carries a `message`,
+  # so in practice this is reached only by an undocumented or malformed body. It
+  # used to render as the bare string "Conexa::ValidationError" and `#to_h` raised
+  # NoMethodError; both now degrade to something a caller can act on.
   class ValidationError < ConexaError
     attr_reader :response, :errors
 
     def initialize(response)
       @response = response
-      @errors   = response['message']&.map do |msg|
-        params = msg.values_at('message', 'parameter_name', 'type', 'url')
-        ParamError.new(*params)
+      @errors   = Array(response.is_a?(Hash) ? response['message'] : nil).filter_map do |msg|
+        next unless msg.is_a?(Hash)
+
+        ParamError.new(*msg.values_at('message', 'parameter_name', 'type', 'url'))
       end
-      super @errors&.map(&:message)&.join(', ')
+
+      super(@errors.any? ? @errors.map(&:message).join(', ') : describe(response))
     end
 
     def to_h
       @errors.map(&:to_h)
     end
+
+    private
+
+    def describe(response)
+      "The API returned an error with no message: #{response.inspect[0, 200]}"
+    end
   end
 
   class MissingCredentialsError < ConexaError

data/lib/conexa/model.rb

@@ -15,16 +15,18 @@ module Conexa
   #
   # == Primary Key
   #
-  # Each resource needs primary_key_attribute for :id alias and operations
-  # that require the resource ID (destroy, save, fetch, etc.):
+  # Each resource declares primary_key_attribute, which defines #id and the
+  # operations that need the resource ID (destroy, save, fetch, etc.):
   #
   #   class Charge < Model
   #     primary_key_attribute :charge_id
   #   end
   #
-  #   charge.id         # => 123 (alias for charge_id)
   #   charge.charge_id  # => 123
   #   charge.chargeId   # => 123 (camelCase alias for backwards compat)
+  #   charge.id         # => 123 — the resource's own key, falling back to a
+  #                     #    plain "id" attribute, which is what write endpoints
+  #                     #    return and what Model#create reads back
   #
   # == Why explicit primary_key_attribute?
   #
@@ -33,18 +35,41 @@ module Conexa
   # instead of "recurring_sale_id". Explicit declaration ensures correctness.
   #
   class Model < ConexaObject
+    extend Deprecatable
+
     def create
-      set_primary_key Conexa::Request.post(self.class.show_url, params: to_hash).call(class_name).attributes['id']
+      created = Conexa::Request.post(self.class.show_url, params: to_hash).call(class_name)
+
+      # A create that answers with no usable body leaves us nothing to identify
+      # the new record by, so there is nothing to re-fetch. Returning the local
+      # object is honest; raising NoMethodError from `nil.attributes` was not.
+      return self unless created.respond_to?(:attributes)
+
+      set_primary_key created.attributes['id']
       fetch
     end
 
     def save
+      # #destroy has always guarded this; #save did not, so an object with no id
+      # silently issued `PATCH /customer/` instead of failing fast.
+      raise RequestError.new('Invalid ID') unless id.present?
+
       update Conexa::Request.patch(self.class.show_url(primary_key), params: unsaved_attributes).call(class_name)
       self
     end
 
     def fetch
-      update self.class.find(primary_key)
+      fetched = self.class.find(primary_key)
+
+      # #update ignores anything with no attributes, which is right for a write
+      # that answers with no body — but a *refresh* that comes back empty must
+      # not quietly leave stale values in place reporting success.
+      unless fetched.respond_to?(:attributes)
+        raise ResponseError.new({ url: self.class.show_url(primary_key) }, nil,
+                                "a API respondeu sem corpo: nada para atualizar")
+      end
+
+      update fetched
       self
     end
 
@@ -75,10 +100,10 @@ module Conexa
     end
 
     class << self
-      # DSL for primary key attribute with :id alias
+      # DSL for the primary key attribute
       # @example
       #   primary_key_attribute :charge_id
-      #   # Generates: charge_id method + chargeId alias + id alias
+      #   # Generates: charge_id + chargeId alias + #id (with an "id" fallback)
       def primary_key_attribute(snake_name)
         camel_name = Util.camelize_str(snake_name.to_s)
 
@@ -87,7 +112,14 @@ module Conexa
         end
 
         alias_method camel_name.to_sym, snake_name
-        alias_method :id, snake_name
+
+        # Not an alias: #id has to keep Model#id's documented fallback to a plain
+        # "id" attribute. Write endpoints answer with {"id": N} rather than the
+        # resource's own key — Model#create depends on exactly that — so aliasing
+        # #id straight to #charge_id silently made the fallback dead code.
+        define_method(:id) do
+          @attributes[snake_name.to_s] || @attributes["id"]
+        end
       end
 
       def create(*args)
@@ -95,19 +127,32 @@ module Conexa
       end
 
       def find_by_id(id, **options)
+        # Surrounding whitespace is a copy-paste artefact, not a different id —
+        # strip it rather than failing. Anything still unusable in a URL is caught
+        # by Request#full_api_url and raised as a RequestError.
+        id = id.to_s.strip if id.is_a?(String)
         raise RequestError.new('Invalid ID') unless id.present?
+
         Conexa::Request.get(show_url(id), params: options).call underscored_class_name
       end
       alias :find :find_by_id
 
       def find_by(params = Hash.new, page = nil, size = nil)
+        # extract_page_size_or_params always returns limit/offset now, and
+        # validates them, so there is no page/size left here to guard.
         params = extract_page_size_or_params(page, size, **params)
-        raise RequestError.new('Invalid page size') if (!params.key?(:limit)) && (params[:page] < 1 or params[:size] < 1)
 
-        Conexa::Request.get(url, params: params).call(
+        result = Conexa::Request.get(url, params: params).call(
           underscored_class_name,
           query_context: { resource_class: self, params: params }
         )
+
+        # A listing always answers with a Result, as the READMEs promise. Without
+        # this, an empty body yielded nil and a bare-array body yielded an Array,
+        # so `.data` / `.pagination` / `.next_page` blew up far from the cause.
+        return result if result.is_a?(Conexa::Result)
+
+        Conexa::Result.new("data" => Array(result), "pagination" => nil)
       end
       alias :find_by_hash :find_by
 
@@ -166,11 +211,32 @@ module Conexa
           return params
         end
 
-        # Explicit legacy pagination (page/size) — deprecated
+        # Legacy pagination (page/size) — deprecated, and broken upstream.
+        #
+        # The API validates `page` and then ignores it, always returning the
+        # first page with offset 0 and hasNext true, so a loop over `page` never
+        # terminates and silently re-yields the same batch. Converting to
+        # limit/offset fixes existing callers instead of leaving them with
+        # plausible wrong answers.
         if params.key?(:page) || params.key?(:size) || page_val.is_a?(Integer)
-          warn "DEPRECATION WARNING: O modelo antigo de paginação (page/size) será removido em 01 de agosto de 2026. Utilize limit e offset."
-          params[:page] ||= page_val || 1
-          params[:size] ||= size_val || 100
+          page = params.delete(:page) || page_val || 1
+          size = params.delete(:size) || size_val || 100
+
+          unless page.is_a?(Integer) && page.positive?
+            raise RequestError, "page must be a positive integer"
+          end
+          unless size.is_a?(Integer) && size.positive?
+            raise RequestError, "size must be a positive integer"
+          end
+
+          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
           return params
         end
 

data/lib/conexa/object.rb

@@ -65,19 +65,40 @@ module Conexa
     end
 
     protected
+    # Merge a response into this object.
+    #
+    # Anything that carries no attributes is a no-op rather than an error. A
+    # write may answer with no body (Request#call then yields nil), with `{}`, or
+    # — for the top-level-array shape Request#run explicitly handles — with an
+    # Array or a scalar, which ConexaObject.convert passes straight through.
+    # None of those can update an object, and none of them should raise a bare
+    # NoMethodError at the caller: that is the failure this release exists to
+    # remove.
+    #
+    # The empty case matters beyond the crash. `removed_attributes` deletes every
+    # key absent from the incoming hash, which is right for a full refresh and
+    # destructive for a write that answers `{}` — that used to wipe the object,
+    # primary key included, and report success.
     def update(attributes)
-      removed_attributes = @attributes.keys - attributes.to_hash.keys
+      return self unless attributes.respond_to?(:to_hash)
+
+      incoming = attributes.to_hash
+      return self if incoming.empty?
+
+      removed_attributes = @attributes.keys - incoming.keys
 
       removed_attributes.each do |key|
         @attributes.delete key
       end
 
-      attributes.each do |key, value|
+      incoming.each do |key, value|
         key = Util.to_snake_case(key.to_s)
 
         @attributes[key] = ConexaObject.convert(value, Util.singularize(key))
         @unsaved_attributes.delete key
       end
+
+      self
     end
 
     def to_hash_value(value, type)
@@ -120,7 +141,7 @@ module Conexa
     end
 
     class << self
-      def convert(response, resource_name = nil, client_key=nil)
+      def convert(response, resource_name = nil)
         case response
         when Array
           response.map{ |i| convert i, resource_name }

data/lib/conexa/request.rb

@@ -23,15 +23,57 @@ module Conexa
         @auth       = options[:auth]        || false
     end
 
+    # Verbs allowed while Conexa.read_only? — GET, plus authentication, without
+    # which read-only mode could not obtain a token in the first place.
+    READ_METHODS = %w(GET).freeze
+
+    # The authentication exemption is tied to these paths, not to the caller's
+    # `auth:` flag. `Request.auth` is public, so trusting the flag alone let any
+    # write opt out of the guard with `Request.auth("/charge/settle/1", …)`.
+    AUTH_PATHS = %w(/auth).freeze
+
     def run
-      response = RestClient::Request.execute request_params
+      enforce_read_only!
 
-      response = MultiJson.decode response.body
-      return {data: response.dig("data") || response, pagination: response.dig("pagination")}
+      response = RestClient::Request.execute request_params
 
+      # A successful write may answer with no body at all: PATCH /charge/settle/:id
+      # documents 204 + empty body as its success response, and
+      # PATCH /contract/end/:id answers 200 with one. With the Oj adapter,
+      # MultiJson.decode("") returns nil *without* raising ParseError, so the
+      # nil has to be caught here rather than in a rescue.
+      body = response.body.to_s
+      return {} if body.strip.empty?
+
+      decoded = MultiJson.decode(body)
+      return {} if decoded.nil?
+
+      # A top-level array (some list endpoints) has no #dig(String).
+      return {data: decoded, pagination: nil} unless decoded.is_a?(Hash)
+
+      {data: decoded["data"] || decoded, pagination: decoded["pagination"]}
+
+      # Connection-level failures first. These subclass RestClient::Exception, so
+      # listing them after it made them unreachable — Ruby matches rescue clauses
+      # top-down. The broad clause then tried to decode their (nil) http_body and
+      # raised NoMethodError instead of the documented ConnectionError.
+      #
+      # All of these carry no response, so there is nothing to classify: they are
+      # failures to reach the API, not answers from it. Note that a real HTTP 408
+      # is RestClient::RequestTimeout, a *superclass* of Exceptions::Timeout, so
+      # it correctly stays in the response taxonomy below.
+      rescue SocketError, RestClient::ServerBrokeConnection,
+             RestClient::SSLCertificateNotVerified,
+             RestClient::Exceptions::Timeout => error
+        raise Conexa::ConnectionError.new error
       rescue RestClient::Exception => error
         begin
-          parsed_error = MultiJson.decode error.http_body
+          # nil for an error carrying no body; MultiJson.decode(nil) returns nil
+          # rather than raising, so the guard has to be here. An error body that
+          # decodes to an array or a scalar has no #[](String) either, and used
+          # to raise TypeError from inside this handler.
+          parsed_error = MultiJson.decode(error.http_body.to_s)
+          parsed_error = {} unless parsed_error.is_a?(Hash)
 
           if error.is_a? RestClient::ResourceNotFound
             if parsed_error['message']
@@ -41,7 +83,8 @@ module Conexa
             end
           else
             if parsed_error['message']
-              raise Conexa::ResponseError.new(request_params, error, parsed_error['message'] + "=> Erros: "+ parsed_error['errors'].to_s)
+              raise Conexa::ResponseError.new(request_params, error,
+                                              describe_api_error(parsed_error), parsed_error)
             else
               raise Conexa::ValidationError.new parsed_error
             end
@@ -50,13 +93,40 @@ module Conexa
           raise Conexa::ResponseError.new(request_params, error)
         end
       rescue MultiJson::ParseError
-        return {} if response.code == 204
-
+        # Only genuinely malformed JSON reaches here — empty and null bodies are
+        # handled above, for every status.
         raise Conexa::ResponseError.new(request_params, response)
-      rescue SocketError
-        raise Conexa::ConnectionError.new $!
-      rescue RestClient::ServerBrokeConnection
-        raise Conexa::ConnectionError.new $!
+    end
+
+    # The API's `message` plus its `errors`, rendered as prose.
+    #
+    # This used to be `message + "=> Erros: " + errors.to_s`, which 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. ResponseError#api_error_messages already normalises both shapes.
+    def describe_api_error(parsed_error)
+      message = parsed_error['message'].to_s
+      details = Conexa::ResponseError.new({}, nil, nil, parsed_error).api_error_messages
+      return message if details.empty?
+
+      "#{message} — #{details.join("; ")}"
+    end
+
+    # @raise [Conexa::ReadOnlyError] when a mutating verb is attempted while
+    #   Conexa.read_only? — checked before the request is executed, so nothing
+    #   reaches the tenant.
+    def enforce_read_only!
+      return unless Conexa.read_only?
+      return if READ_METHODS.include?(method.to_s.upcase)
+      return if @auth && AUTH_PATHS.include?(path)
+
+      # Deliberately `path`, not `full_api_url`: the latter validates the URL and
+      # can raise RequestError, which would win over this one purely because the
+      # message is interpolated first. Read-only is a policy — it applies whatever
+      # the path looks like.
+      raise Conexa::ReadOnlyError,
+            "Conexa is in read-only mode: refusing #{method.to_s.upcase} #{path}. " \
+            "Unset config.read_only (or CONEXA_READ_ONLY) to allow writes."
     end
 
     def call(resource_name, query_context: nil)
@@ -120,6 +190,15 @@ module Conexa
         url += '?' + URI.encode_www_form(query)
       end
 
+      # An unusable path (a stray space in an id, say) would otherwise surface as
+      # URI::InvalidURIError from inside RestClient — outside Conexa::ConexaError,
+      # so no caller could rescue it meaningfully.
+      begin
+        URI.parse(url)
+      rescue URI::InvalidURIError
+        raise Conexa::RequestError, "Invalid request path: #{path.inspect}"
+      end
+
       url
     end
   end

data/lib/conexa/resources/charge.rb

@@ -29,29 +29,82 @@ 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
-    # @param params [Hash] optional payment details
+    #
+    # Moves money and, on a configured tenant, issues an NF-e. Not safe to retry
+    # blindly: a second attempt on a settled charge answers 422 CHARGE_11.
+    #
+    # The API answers 204 with an empty body on success.
+    #
+    # @param params [Hash] settlement details
+    # @option params [String] :settlement_date required, yyyy-MM-dd
+    # @option params [Hash] :receiving_method required, {id:, installments_quantity:}
+    # @option params [Integer] :account_id required
+    # @option params [Float] :paid_amount defaults to the charge amount, without interest
+    # @option params [Boolean] :send_email defaults to false
     # @return [self]
     def settle(params = {})
-      Conexa::Request.post(self.class.show_url("settle", primary_key), params: params).call(class_name)
+      Conexa::Request.patch(self.class.show_url("settle", primary_key), params: params).call(class_name)
       self
     end
 

data/lib/conexa/resources/company.rb

@@ -1,7 +1,26 @@
 # frozen_string_literal: true
 
 module Conexa
-  class Company  < Model
+  # Company resource (Empresa / unidade)
+  #
+  # @example List companies
+  #   Conexa::Company.all(limit: 50)
+  #
+  # @example Find a company
+  #   Conexa::Company.find(3)
+  class Company < Model
+    class << self
+      # Model#url pluralizes by appending "s", which yields "/companys" and 404s.
+      # Any resource with an irregular English plural has to override this — see
+      # spec/contract/api_contract_spec.rb, which checks every resource's URL
+      # against the published collection.
+      def url(*params)
+        ["/companies", *params].join '/'
+      end
 
+      def show_url(*params)
+        ["/company", *params].join '/'
+      end
+    end
   end
 end