conexa 0.1.1 → 0.2.1

data/lib/conexa/resources/contract.rb

@@ -3,16 +3,71 @@
 module Conexa
   # Contract resource for recurring billing contracts
   #
-  # @example Create a contract
-  #   contract = Conexa::Contract.create(
-  #     customer_id: 127,
-  #     plan_id: 5,
-  #     start_date: '2024-01-01',
-  #     payment_day: 10
+  # == Creating a contract
+  #
+  # Required: +plan_id+, +customer_id+, +payment_frequency+ (+monthly+,
+  # +bimonthly+, +quarterly+, +semester+ or +yearly+) and +start_date+.
+  #
+  #   Conexa::Contract.create(
+  #     plan_id: 5, customer_id: 127,
+  #     payment_frequency: 'monthly', start_date: '2026-01-01'
+  #   )
+  #
+  # === +due_day+ is conditionally required *and* conditionally forbidden
+  #
+  # Required on a customer's **first** contract (or when they use automatic
+  # invoicing); **rejected** on every later one, which inherits the customer's
+  # +defaultDueDay+:
+  #
+  #   422 CONTRACT_RECURRING_SALE_10
+  #   "The due day can not be informed for customers who already have a contract"
+  #
+  # Code that always sends +due_day+ works at onboarding and fails forever after.
+  # Read the code off the exception rather than the message:
+  #
+  #   rescue Conexa::ResponseError => e
+  #     retry_without_due_day if e.api_error_codes.include?('CONTRACT_RECURRING_SALE_10')
+  #   end
+  #
+  # === Creating, charging and settling in one call
+  #
+  # +generate_sales: 'firstOccurrenceSettleRetroactive'+ also generates *and
+  # settles* retroactive charges, and then requires +expense_settlement+. It
+  # replaces a three-call sequence in which each step can fail on its own.
+  #
+  #   Conexa::Contract.create(
+  #     plan_id: 5, customer_id: 127,
+  #     payment_frequency: 'monthly', start_date: '2026-01-01',
+  #     generate_sales: 'firstOccurrenceSettleRetroactive',
+  #     expense_settlement: { receiving_method_id: 53, account_id: 1 }
   #   )
   #
+  # Other documented values: +firstOccurrence+ (default), +currentOccurrence+,
+  # +nextOccurrence+.
+  #
+  # === Other documented fields
+  #
+  # +end_date+, +first_due_date+ (required when the customer uses automatic
+  # invoicing), +fidelity_date+, +amount+, +discount_value+, +seller_id+,
+  # +contract_summary+, +notes+, +membership_fee+, +nfse_description+,
+  # +prorata_type+ (+startOfMonth+ / +notCalculate+ / +perDueDate+), +refund+
+  # (an explicit +nil+ opts out even when the plan configures one),
+  # +complementary_services+ (array), +extra_fields+ (array).
+  #
+  # +cost_center_id+ is *not* accepted on create — it 400s — even though it is
+  # present when the contract is read back.
+  #
   # @example End a contract
-  #   Conexa::Contract.end_contract(456, end_date: '2024-12-31')
+  #   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)
@@ -20,49 +75,111 @@ module Conexa
   #   @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
 
-    # End/terminate this contract
-    # @param params [Hash] options including :end_date, :reason
+    # Set this contract's end date — closing it, or amending an existing closure.
+    #
+    # The endpoint is documented as "encerra um contrato ativo **ou atualiza a
+    # data de encerramento**": it both closes and amends, and a future date on an
+    # already-closed contract **reopens** it. `end_contract` is kept as an alias,
+    # but the name understates what the call does.
+    #
+    # A contract cannot be closed retroactively past a day that already has
+    # invoiced sales (422 CONTRACT_RECURRING_SALE_23).
+    #
+    # The API may answer with an empty body on success.
+    #
+    # @param params [Hash]
+    # @option params [String] :date required, yyyy-MM-dd — the closing date
+    # @option params [Integer] :reason_id closing-reason id, from
+    #   Listagem de Contratos > Outros Cadastros > Motivo de Encerramento de Contrato
+    # @option params [Boolean] :unlink_customer unlinks DDRs, mailboxes, extensions
+    #   and recurring sales. Requires date <= today and no other active contracts;
+    #   ends *all* the customer's recurring sales and cancels their uninvoiced sales.
+    # @option params [String] :end_date deprecated alias for +:date+
     # @return [self]
-    def end_contract(params = {})
-      Conexa::Request.post(self.class.show_url("end", primary_key), params: params).call(class_name)
+    def set_end_date(params = {})
+      params = self.class.normalize_end_params(params)
+      Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
       self
     end
+    alias_method :end_contract, :set_end_date
 
     class << self
-      # End a contract by ID
+      # Set a contract's end date by ID
+      # @see #set_end_date
       # @param id [Integer, String] contract ID
-      # @param params [Hash] options including :end_date, :reason
       # @return [Contract]
-      def end_contract(id, params = {})
-        find(id).end_contract(params)
+      def set_end_date(id, params = {})
+        find(id).set_end_date(params)
+      end
+      alias_method :end_contract, :set_end_date
+
+      # @deprecated Use {Conexa::Util.normalize_end_date_param}, which both "end"
+      #   endpoints share.
+      # @api private
+      def normalize_end_params(params)
+        Util.normalize_end_date_param(params)
       end
 
       # Create contract with custom product items

data/lib/conexa/resources/credit_card.rb

@@ -1,9 +1,49 @@
 # frozen_string_literal: true
 
 module Conexa
+  # Credit card, registered against the customer through Cielo.
+  #
+  # **Write-only.** API v2 exposes `POST /creditCard` and nothing else — the card
+  # number and CVC live encrypted at Cielo, not in Conexa, so there is nothing to
+  # read back. Verified against a live tenant on 2026-08-12:
+  #
+  #   GET /creditCard      => 404 "Unable to resolve the request"
+  #   GET /creditCard/:id  => 404 "unable to find the requested action \"view\""
+  #
+  # Neither is the "does not exist or you have no permission to access it"
+  # wording the API uses for a resource an account cannot see, and the collection
+  # documents a 403 for authorization — so this is the shape of the API, not a
+  # feature switched off for one tenant.
+  #
+  # `#save` and `#destroy` are left in place but are **undocumented and
+  # unverified**: the collection describes only `POST`, and the documented
+  # behaviour of `default:` and `enable_recurring:` — re-registering a card
+  # changes which one is default, or turns recurrence off — reads as if there is
+  # no update path at all. They were not probed, because probing them means
+  # writing. Treat a 404 from either as expected rather than as a bug.
+  #
+  # @example Register a card
+  #   Conexa::CreditCard.create(
+  #     customer_id: 127, number: '4111111111111111',
+  #     expiration_date: '12/26', cvc: '123', name: 'JOAO DA SILVA',
+  #     default: true, enable_recurring: true
+  #   )
   class CreditCard < Model
     primary_key_attribute :credit_card_id
 
+    NO_READ = "a API v2 não expõe leitura de cartão de crédito: só " \
+              "POST /creditCard é documentado, e GET /creditCard[/:id] responde 404. " \
+              "Os dados do cartão ficam na Cielo, não no Conexa."
+
+    # Model#create re-fetches the created record to pick up server-side defaults.
+    # There is no read here, so the id from the response is all there is.
+    # @return [self]
+    def create
+      created = Conexa::Request.post(self.class.show_url, params: to_hash).call(class_name)
+      set_primary_key created.attributes['id'] if created.respond_to?(:attributes)
+      self
+    end
+
     class << self
       def url(*params)
         ["/creditCard", *params].join '/'
@@ -12,6 +52,12 @@ module Conexa
       def show_url(*params)
         ["/creditCard", *params].join '/'
       end
+
+      # Every read name Model provides, refused with an explanation rather than
+      # left to return a bare Conexa::NotFound that reads as "no such card".
+      %i[all where find find_by find_by_hash find_by_id].each do |name|
+        define_method(name) { |*, **| raise RequestError, NO_READ }
+      end
     end
   end
 end

data/lib/conexa/resources/recurring_sale.rb

@@ -4,13 +4,23 @@ module Conexa
   class RecurringSale < Model
     primary_key_attribute :recurring_sale_id
 
-    # End/terminate a recurring sale
-    # @param params [Hash] optional parameters (e.g., endDate)
+    # Set this recurring sale's end date — closing it, or amending an existing
+    # closure.
+    #
+    # Like the contract endpoint, this one is documented as "encerra uma venda
+    # recorrente ativa **ou atualiza a data de encerramento**".
+    #
+    # @param params [Hash]
+    # @option params [String] :date required, yyyy-MM-dd — the closing date
+    # @option params [String] :end_date deprecated alias for +:date+; the API
+    #   rejects the +endDate+ it camelizes to
     # @return [self]
     def end_recurring_sale(params = {})
-      Conexa::Request.post(self.class.show_url("end", primary_key), params: params).call(class_name)
+      params = Util.normalize_end_date_param(params)
+      Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
       self
     end
+    alias_method :set_end_date, :end_recurring_sale
 
     class << self
       def url(*params)
@@ -21,13 +31,14 @@ module Conexa
         ["/recurringSale", *params].join '/'
       end
 
-      # End a recurring sale by ID
+      # Set a recurring sale's end date by ID
+      # @see #end_recurring_sale
       # @param id [Integer, String] recurring sale ID
-      # @param params [Hash] optional parameters (e.g., endDate)
       # @return [RecurringSale]
       def end_recurring_sale(id, params = {})
         find(id).end_recurring_sale(params)
       end
+      alias_method :set_end_date, :end_recurring_sale
     end
   end
 end

data/lib/conexa/resources/result.rb

@@ -18,19 +18,37 @@ module Conexa
       @attributes["pagination"]
     end
 
+    # @return [Boolean] always a boolean — it used to yield nil when there was no
+    #   pagination at all, which is falsy but not `false`, and leaks out of any
+    #   caller that serialises or compares the result.
     def has_next?
-      pagination && pagination.has_next == true
+      pagination.respond_to?(:has_next) && pagination.has_next == true
     end
 
     def next_page
       raise StopIteration, "No more pages" unless has_next?
-      raise "No query context available for next_page" unless @query_context
+      raise Conexa::RequestError, "No query context available for next_page" unless @query_context
+
+      limit  = pagination.limit
+      offset = pagination.offset
+      unless limit.is_a?(Integer) && offset.is_a?(Integer)
+        raise Conexa::ResponseError.new(@query_context[:params], nil,
+                                        "pagination is missing limit/offset " \
+                                        "(limit=#{limit.inspect}, offset=#{offset.inspect}), " \
+                                        "so the next page cannot be computed")
+      end
 
       resource_class = @query_context[:resource_class]
-      next_params = Marshal.load(Marshal.dump(@query_context[:params]))
 
-      next_params[:limit] = pagination.limit
-      next_params[:offset] = pagination.offset + pagination.limit
+      begin
+        next_params = Marshal.load(Marshal.dump(@query_context[:params]))
+      rescue TypeError
+        # A non-marshallable filter (a Proc, an IO) in the original query.
+        next_params = @query_context[:params].dup
+      end
+
+      next_params[:limit] = limit
+      next_params[:offset] = offset + limit
       next_params.delete(:page)
       next_params.delete(:size)
 

data/lib/conexa/util.rb

@@ -47,25 +47,65 @@ module Conexa
         string.to_s.strip.gsub(/[\s\-]+/, '_').to_sym
       end
 
+      # Both "end" endpoints — PATCH /contract/end/:id and
+      # PATCH /recurringSale/end/:id — document the closing date as `date`. The
+      # gem used to send `end_date`, which camelizes to `endDate` and is rejected:
+      # "endDate field does not exist or is not available in the company".
+      #
+      # Both key spellings are handled, and both are removed. Checking only the
+      # symbol `:date` would leave a caller's string `"date"` in place and add a
+      # second, colliding key — camelize_hash folds the two into one and the last
+      # one wins, so the deprecated value would silently replace the real one.
+      #
+      # @param params [Hash] caller params, possibly using the old name
+      # @return [Hash] a copy with end_date folded into date
+      def normalize_end_date_param(params)
+        params = params.dup
+
+        # Collapse both spellings of each key up front. Leaving one behind would
+        # let camelize_hash fold two `date` keys into one, last-write-wins — which
+        # is how the deprecated value once silently replaced the real one.
+        legacy   = [params.delete(:end_date), params.delete("end_date")].compact.first
+        explicit = [params.delete(:date), params.delete("date")].compact.first
+
+        warn_end_date_renamed if legacy
+
+        # An explicit date wins; a key present with a nil value is not one.
+        date = explicit || legacy
+        params[:date] = date unless date.nil?
+        params
+      end
+
       def to_snake_case str
         str.gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, '')
       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,
+      # extraFields, bookingModels, visitors, costCenters, ...), and a snake_case
+      # key inside one is rejected outright.
       def camelize_hash(hash)
         return {} if hash.nil?
 
-        new_hash = {}
-
-        hash.each do |key, value|
-          if value.is_a?(Hash)
-            new_hash[camel_case_lower(key).to_sym] = camelize_hash(value)
-          else
-            new_hash[camel_case_lower(key).to_sym] = value
-          end
+        hash.each_with_object({}) do |(key, value), new_hash|
+          new_hash[camel_case_lower(key).to_sym] = camelize_value(value)
         end
+      end
 
-        new_hash
+      def camelize_value(value)
+        case value
+        when Hash  then camelize_hash(value)
+        when Array then value.map { |element| camelize_value(element) }
+        else value
+        end
       end
 
       def camelize_str(str)

data/lib/conexa/version.rb

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

data/lib/conexa.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "conexa/version"
-require_relative "conexa/authenticator"
+# 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"
@@ -9,8 +10,6 @@ require_relative "conexa/core_ext"
 require_relative "conexa/errors"
 require_relative "conexa/util"
 require_relative "conexa/configuration"
-require_relative "conexa/order_common"
-require_relative "conexa/token_manager"
 
 
 Dir[File.expand_path('../conexa/resources/*.rb', __FILE__)].map do |path|
@@ -32,4 +31,42 @@ module Conexa
   def self.api_endpoint
     configuration.api_host + "/index.php/api/v2"
   end
+
+  # Key for the block-scoped read-only override. Thread-local so a guarded block
+  # in one thread cannot relax or tighten another.
+  READ_ONLY_KEY = :conexa_read_only
+
+  # Is writing currently forbidden?
+  #
+  # True inside a {read_only} block, or whenever `configuration.read_only` is set
+  # (which itself defaults from CONEXA_READ_ONLY).
+  #
+  # @return [Boolean]
+  def self.read_only?
+    scoped = Thread.current[READ_ONLY_KEY]
+    return scoped unless scoped.nil?
+
+    !!configuration&.read_only
+  end
+
+  # Run a block with writes forbidden, then restore the previous state.
+  #
+  # Useful for auditing or reporting code that should never mutate a tenant,
+  # without having to reconfigure the client globally.
+  #
+  # @example
+  #   Conexa.read_only do
+  #     Conexa::Charge.all(status: "pending")   # fine
+  #     Conexa::Charge.settle(555)              # raises Conexa::ReadOnlyError
+  #   end
+  #
+  # @param enabled [Boolean] pass false to explicitly allow writes in the block
+  # @return [Object] the block's return value
+  def self.read_only(enabled = true)
+    previous = Thread.current[READ_ONLY_KEY]
+    Thread.current[READ_ONLY_KEY] = enabled
+    yield
+  ensure
+    Thread.current[READ_ONLY_KEY] = previous
+  end
 end