conexa 0.0.8 → 0.1.0

data/REFERENCE.md

@@ -14,17 +14,25 @@ Conexa is a Brazilian SaaS platform for **recurring billing**, **subscription ma
 - **Sale** - One-time sale (not recurring)
 - **RecurringSale** - Recurring sale item within a contract
 - **Plan** - Pricing plan with products and periodicities
-- **Product** - Billable item/service
+- **Product** - Billable item/service (now supports full CRUD)
 - **InvoicingMethod** - Payment method configuration (boleto, PIX, credit card)
+- **ReceivingMethod** - Receiving method configuration (cash, transfer, card machine)
+- **PaymentMethod** - Payment method type (boleto, PIX, cartão)
+- **BillCategory** - Bill expense category
+- **BillSubcategory** - Bill expense subcategory
+- **CostCenter** - Cost center for expense allocation
+- **Account** - Bank account
+- **ServiceCategory** - Service category for plans
 - **Person** - Requester (solicitante) linked to a customer
 - **Bill** - Financial bill (conta a pagar)
 - **Supplier** - Supplier with PF/PJ data
+- **RoomBooking** - Room booking with checkin/checkout (Conexa Coworking)
 
 ## Installation
 
 ```ruby
 # Gemfile
-gem 'conexa', '~> 0.0.7'
+gem 'conexa', '~> 0.1.0'
 
 # Or install directly
 gem install conexa
@@ -694,12 +702,16 @@ product = Conexa::Product.find(100)
 product.name  # => "Mensalidade"
 
 # List products
-products = Conexa::Product.all(company_id: [3])
-```
+products = Conexa::Product.all(company_id: [3], limit: 50)
+
+# Create product
+product = Conexa::Product.create(name: 'Novo Produto', company_id: 3)
 
-**API endpoints:** `GET /product/:id`, `GET /products`
+# Delete product
+Conexa::Product.destroy(100)
+```
 
-**Note:** Products cannot be created/updated via this gem. `save` raises `NoMethodError`.
+**API endpoints:** `GET /product/:id`, `GET /products`, `POST /product`, `DELETE /product/:id`
 
 ---
 
@@ -855,7 +867,7 @@ supplier.save
 supplier.destroy
 ```
 
-**API endpoints:** `POST /supplier`, `GET /supplier/:id`, `PATCH /supplier/:id`, `DELETE /supplier/:id`, `GET /supplier` (list)
+**API endpoints:** `POST /supplier`, `GET /supplier/:id`, `PATCH /supplier/:id`, `DELETE /supplier/:id`, `GET /suppliers`
 
 **Create attributes:**
 - `name` - Supplier name (required)
@@ -1020,27 +1032,131 @@ person.destroy
 
 ### Pagination
 
-All `#all` and `#find_by` methods support pagination:
+#### New Pagination (recommended) — `limit`/`offset`/`hasNext`
+
+All `#all` and `#find_by` methods use `limit`/`offset` by default. When no pagination params are passed, the gem defaults to `limit: 100, offset: 0`.
+
+```ruby
+# Page 1, 50 items
+result = Conexa::Customer.all(limit: 50)
+
+result.data           # => Array of customers
+result.pagination.limit    # => 50
+result.pagination.offset   # => 0
+result.has_next?      # => true/false
+result.empty?         # => false
+
+# Iterate all pages using next_page
+result = Conexa::Customer.all(limit: 100)
+loop do
+  result.each { |customer| process(customer) }
+  break unless result.has_next?
+  result = result.next_page
+end
+
+# Or manually with offset
+offset = 0
+loop do
+  result = Conexa::Customer.all(limit: 100, offset: offset)
+  break if result.empty?
+  result.each { |customer| process(customer) }
+  break unless result.has_next?
+  offset += 100
+end
+```
+
+**`next_page`** — Fetches the next page automatically, preserving all original filter params. Raises `StopIteration` when there are no more pages.
+
+**`has_next?`** — Returns `true` if more pages are available.
+
+#### Legacy Pagination (deprecated — removed 2026-08-01)
+
+If `page:` or `size:` is explicitly passed, the gem uses the old pagination model
+(emitting a deprecation warning):
 
 ```ruby
-# Page 1, 50 items per page
+# Emits: DEPRECATION WARNING: O modelo antigo de paginação...
 result = Conexa::Customer.all(page: 1, size: 50)
 
 result.data        # => Array of customers
 result.pagination  # => { "page" => 1, "size" => 50, "total" => 150 }
 result.empty?      # => false
+```
+
+#### Migration Guide: Legacy → New Pagination
 
-# Iterate all pages
+The legacy `page`/`size` pagination is deprecated and will be removed on **2026-08-01**. Follow these steps to migrate:
+
+**Step 1 — Replace `page`/`size` with `limit`/`offset`:**
+
+```ruby
+# BEFORE (legacy)
+result = Conexa::Customer.all(page: 1, size: 50)
+result = Conexa::Customer.all(page: 2, size: 50)
+
+# AFTER (new)
+result = Conexa::Customer.all(limit: 50)               # offset defaults to 0
+result = Conexa::Customer.all(limit: 50, offset: 50)   # second page
+```
+
+Conversion formula: `offset = (page - 1) * size`
+
+**Step 2 — Update pagination metadata access:**
+
+```ruby
+# BEFORE
+result.pagination  # => { "page" => 1, "size" => 50, "total" => 150 }
+total_pages = (result.pagination["total"].to_f / size).ceil
+
+# AFTER
+result.pagination.limit      # => 50
+result.pagination.offset     # => 0
+result.pagination.has_next   # => true/false
+```
+
+**Step 3 — Update iteration loops:**
+
+```ruby
+# BEFORE
 page = 1
 loop do
   result = Conexa::Customer.all(page: page, size: 100)
   break if result.empty?
-
-  result.each { |customer| process(customer) }
+  result.each { |c| process(c) }
   page += 1
 end
+
+# AFTER (using next_page)
+result = Conexa::Customer.all(limit: 100)
+loop do
+  result.each { |c| process(c) }
+  break unless result.has_next?
+  result = result.next_page
+end
+```
+
+**Step 4 — Remove positional arguments:**
+
+```ruby
+# BEFORE
+Conexa::Customer.all(2, 50)           # page 2, size 50
+Conexa::Customer.find_by({}, 1, 20)   # page 1, size 20
+
+# AFTER
+Conexa::Customer.all(limit: 50, offset: 50)
+Conexa::Customer.find_by(limit: 20)
 ```
 
+**Quick reference:**
+
+| Legacy | New |
+|---|---|
+| `page: 1, size: 50` | `limit: 50` (offset defaults to 0) |
+| `page: N, size: S` | `limit: S, offset: (N-1)*S` |
+| `pagination["total"]` | `pagination.has_next` |
+| `pagination["page"]` | `pagination.offset` |
+| Positional `(page, size)` | Keyword `limit:`, `offset:` |
+
 ### Result Object
 
 API calls return `Conexa::Result` objects:
@@ -1109,7 +1225,7 @@ Conexa::Charge.all(
 
 ### Rate Limiting
 
-The API enforces a limit of 100 requests per minute. Response headers:
+The API enforces a limit of 100 requests per minute (changing to **60 requests per minute** on 2026-04-27). Response headers:
 - `X-Rate-Limit-Limit` - Maximum requests per minute
 - `X-Rate-Limit-Remaining` - Remaining requests
 - `X-Rate-Limit-Reset` - Seconds until limit resets
@@ -1127,13 +1243,21 @@ The API enforces a limit of 100 requests per minute. Response headers:
 | Sale | yes | yes | yes | yes | yes | billed?, paid?, editable? |
 | RecurringSale | yes | yes | yes | yes | yes | end_recurring_sale |
 | Plan | yes | yes | yes | - | yes | - |
-| Product | yes | yes | - | - | - | - |
+| Product | yes | yes | yes | - | yes | - |
 | InvoicingMethod | yes | yes | yes | yes | yes | - |
+| ReceivingMethod | yes | yes | - | - | - | - |
+| PaymentMethod | yes | yes | - | - | - | - |
+| BillCategory | yes | yes | - | - | - | - |
+| BillSubcategory | yes | yes | - | - | - | - |
+| CostCenter | yes | yes | - | - | - | - |
+| Account | yes | yes | - | - | - | - |
+| ServiceCategory | yes | yes | - | - | - | - |
 | Bill | yes | yes | yes | - | - | - |
 | Company | yes | yes | yes | yes | yes | - |
 | Supplier | yes | yes | yes | yes | yes | - |
 | CreditCard | yes | - | yes | yes | yes | - |
 | Person | - | - | yes | yes | yes | - |
+| RoomBooking | yes | yes | yes | - | - | cancel, checkout, checkin |
 
 **Legend:** `yes` = available, `-` = not available (raises NoMethodError or not implemented)
 

data/lib/conexa/authenticator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'jwt'
 
 

data/lib/conexa/configuration.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Conexa
   class Configuration
     attr_accessor :api_token, :api_host

data/lib/conexa/core_ext.rb

@@ -1,9 +1,14 @@
-class Object
-  def blank?
-    respond_to?(:empty?) ? !!empty? : !self
-  end
+# frozen_string_literal: true
+
+# Only define blank?/present? if not already provided (e.g., by ActiveSupport)
+unless Object.method_defined?(:blank?)
+  class Object
+    def blank?
+      respond_to?(:empty?) ? !!empty? : !self
+    end
 
-  def present?
-    !blank?
+    def present?
+      !blank?
+    end
   end
 end

data/lib/conexa/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Conexa
   class ConexaError < StandardError
   end
@@ -38,11 +40,11 @@ module Conexa
 
     def initialize(response)
       @response = response
-      @errors   = response['message']&.map do |message|
-        params = error.values_at('message', 'parameter_name', 'type', 'url')
+      @errors   = response['message']&.map do |msg|
+        params = msg.values_at('message', 'parameter_name', 'type', 'url')
         ParamError.new(*params)
       end
-      super @errors&.map(&:message).join(', ')
+      super @errors&.map(&:message)&.join(', ')
     end
 
     def to_h

data/lib/conexa/model.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 module Conexa
   # Base class for all API resources (Customer, Charge, Contract, etc.)
   #
   # == Attribute Access
-  # 
+  #
   # Attributes are automatically accessible via method_missing:
   #   customer.name           # => "Empresa ABC"
   #   customer.company_id     # => 3
@@ -31,29 +33,11 @@ module Conexa
   # instead of "recurring_sale_id". Explicit declaration ensures correctness.
   #
   class Model < ConexaObject
-    class << self
-      # DSL for primary key attribute with :id alias
-      # @example
-      #   primary_key_attribute :charge_id
-      #   # Generates: charge_id method + chargeId alias + id alias
-      def primary_key_attribute(snake_name)
-        camel_name = Util.camelize_str(snake_name.to_s)
-
-        define_method(snake_name) do
-          @attributes[snake_name.to_s]
-        end
-
-        alias_method camel_name.to_sym, snake_name
-        alias_method :id, snake_name
-      end
-    end
-
     def create
       set_primary_key Conexa::Request.post(self.class.show_url, params: to_hash).call(class_name).attributes['id']
       fetch
     end
 
-
     def save
       update Conexa::Request.patch(self.class.show_url(primary_key), params: unsaved_attributes).call(class_name)
       self
@@ -86,11 +70,26 @@ module Conexa
 
     def destroy
       raise RequestError.new('Invalid ID') unless id.present?
-      update Conexa::Request.delete( self.class.show_url(primary_key) ).call(class_name)
+      update Conexa::Request.delete(self.class.show_url(primary_key)).call(class_name)
       self
     end
 
     class << self
+      # DSL for primary key attribute with :id alias
+      # @example
+      #   primary_key_attribute :charge_id
+      #   # Generates: charge_id method + chargeId alias + id alias
+      def primary_key_attribute(snake_name)
+        camel_name = Util.camelize_str(snake_name.to_s)
+
+        define_method(snake_name) do
+          @attributes[snake_name.to_s]
+        end
+
+        alias_method camel_name.to_sym, snake_name
+        alias_method :id, snake_name
+      end
+
       def create(*args)
         self.new(*args).create
       end
@@ -101,18 +100,19 @@ module Conexa
       end
       alias :find :find_by_id
 
-
       def find_by(params = Hash.new, page = nil, size = nil)
         params = extract_page_size_or_params(page, size, **params)
-        raise RequestError.new('Invalid page size') if params[:page] < 1 or params[:size] < 1
+        raise RequestError.new('Invalid page size') if (!params.key?(:limit)) && (params[:page] < 1 or params[:size] < 1)
 
-        Conexa::Request.get(url, params: params).call underscored_class_name
+        Conexa::Request.get(url, params: params).call(
+          underscored_class_name,
+          query_context: { resource_class: self, params: params }
+        )
       end
       alias :find_by_hash :find_by
 
       def all(*args, **params)
-        params = extract_page_size_or_params(*args, **params)
-        find_by params
+        find_by(params, *args)
       end
       alias :where :all
 
@@ -131,7 +131,8 @@ module Conexa
       end
 
       def class_name
-        self.name.split('::').last.downcase
+        name = self.name.split('::').last
+        name[0].downcase + name[1..]
       end
 
       def underscored_class_name
@@ -139,8 +140,43 @@ module Conexa
       end
 
       def extract_page_size_or_params(*args, **params)
-        params[:page]  ||= args[0] || 1
-        params[:size] ||= args[1] || 100
+        if args[0].is_a?(Hash)
+          params = args[0].merge(params)
+          page_val = nil
+        else
+          page_val = args[0]
+        end
+        size_val = args[1]
+
+        # Explicit new pagination (limit/offset)
+        if params.key?(:limit)
+          unless params[:limit].is_a?(Integer) && params[:limit].positive?
+            raise RequestError, "limit must be a positive integer"
+          end
+
+          params[:offset] ||= size_val if size_val.is_a?(Integer)
+          params[:offset] ||= 0
+
+          unless params[:offset].is_a?(Integer) && params[:offset] >= 0
+            raise RequestError, "offset must be a non-negative integer"
+          end
+
+          params.delete(:page)
+          params.delete(:size)
+          return params
+        end
+
+        # Explicit legacy pagination (page/size) — deprecated
+        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
+          return params
+        end
+
+        # Default: new pagination
+        params[:limit] = 100
+        params[:offset] = 0
         params
       end
     end

data/lib/conexa/object.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Conexa
   # Base class for all Conexa objects with dynamic attribute access
   #
@@ -24,8 +26,6 @@ module Conexa
     end
 
     def initialize(response = {})
-      # raise MissingCredentialsError.new("Missing :client_key for extra options #{options}") if options && !options[:client_key]
-
       @attributes = Hash.new
       @unsaved_attributes = Set.new
 
@@ -57,21 +57,13 @@ module Conexa
       end]
     end
 
-    def respond_to?(name, include_all = false)
-      return true if name.to_s.end_with? '='
+    def respond_to_missing?(name, include_private = false)
+      name_str = Util.to_snake_case(name.to_s)
+      return true if name_str.end_with?('=')
 
-      @attributes.has_key?(name.to_s) || super
+      @attributes.key?(name_str) || @attributes.key?(name_str.to_sym) || super
     end
 
-    # def to_s
-    #   attributes_str = ''
-    #   (attributes.keys - ['id', 'object']).sort.each do |key|
-    #     attributes_str += " \033[1;33m#{key}:\033[0m#{self[key].inspect}" unless self[key].nil?
-    #   end
-    #   "\033[1;31m#<#{self.class.name}:\033[0;32m#{id}#{attributes_str}\033[0m\033[0m\033[1;31m>\033[0;32m"
-    # end
-    # # alias :inspect :to_s
-
     protected
     def update(attributes)
       removed_attributes = @attributes.keys - attributes.to_hash.keys
@@ -111,7 +103,12 @@ module Conexa
         end
 
         if args.size == 0
-          return self[name] || self[name.to_sym]
+          if @attributes.key?(name)
+            return @attributes[name]
+          elsif @attributes.key?(name.to_sym)
+            return @attributes[name.to_sym]
+          end
+          return nil
         end
       end
 
@@ -122,7 +119,6 @@ module Conexa
       super name, *args, &block
     end
 
-
     class << self
       def convert(response, resource_name = nil, client_key=nil)
         case response
@@ -149,7 +145,6 @@ module Conexa
 
       def capitalize_name(name)
         name.split('_').collect(&:capitalize).join
-        # name.gsub(/(\A\w|\_\w)/){ |str| str.gsub('_', '').upcase }
       end
     end
   end

data/lib/conexa/{order_commom.rb → order_common.rb}

@@ -1,9 +1,9 @@
-module Conexa
-  class OrderCommom < Model
+# frozen_string_literal: true
 
-    # def self.url(*params)
-    #   ["/#{ CGI.escape underscored_class_name }", *params].join '/'
-    # end
+module Conexa
+  class OrderCommon < Model
+    # Keep old name as alias for backwards compatibility
+    OrderCommom = self
 
     #
     # Request refund to Conexa api for this order

data/lib/conexa/request.rb

@@ -1,9 +1,9 @@
+# frozen_string_literal: true
+
 require 'uri'
 require 'rest_client'
 require 'multi_json'
 
-
-
 module Conexa
   class Request
     DEFAULT_HEADERS = {
@@ -29,7 +29,6 @@ module Conexa
       response = MultiJson.decode response.body
       return {data: response.dig("data") || response, pagination: response.dig("pagination")}
 
-
       rescue RestClient::Exception => error
         begin
           parsed_error = MultiJson.decode error.http_body
@@ -60,16 +59,18 @@ module Conexa
         raise Conexa::ConnectionError.new $!
     end
 
-    def call(ressource_name)
+    def call(resource_name, query_context: nil)
       dt = run
 
       if dt[:pagination]
-        return ConexaObject.convert({
-          data: ConexaObject.convert(dt[:data], ressource_name),
+        result = ConexaObject.convert({
+          data: ConexaObject.convert(dt[:data], resource_name),
           pagination: ConexaObject.convert(dt[:pagination], "pagination")}, "result")
+        result.instance_variable_set(:@query_context, query_context) if query_context
+        return result
       end
 
-      ConexaObject.convert(dt[:data], ressource_name)
+      ConexaObject.convert(dt[:data], resource_name)
     end
 
     def self.get(url, options={})
@@ -105,7 +106,7 @@ module Conexa
       @parameters = Util.camelize_hash(@parameters)
       aux.merge!({ payload:   MultiJson.encode(@parameters)}) unless %w(GET DELETE).include? method
 
-      extra_headers = DEFAULT_HEADERS
+      extra_headers = DEFAULT_HEADERS.dup
       extra_headers[:authorization] = "Bearer #{Conexa.configuration.api_token}" unless @auth
       extra_headers[:params] = @parameters if method == "GET"
       aux.merge!({ headers: extra_headers })

data/lib/conexa/resources/account.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Conexa
+  # Account resource (Conta Bancária)
+  #
+  # @example Find an account
+  #   account = Conexa::Account.find(23)
+  #   account.name  # => "Banco do Brasil"
+  #
+  # @example List accounts
+  #   accounts = Conexa::Account.all(limit: 50)
+  #
+  # @!attribute [r] account_id
+  #   @return [Integer] Account ID (also accessible as #id)
+  # @!attribute [r] name
+  #   @return [String] Account name
+  # @!attribute [r] is_active
+  #   @return [Boolean] Whether the account is active
+  #
+  class Account < Model
+    primary_key_attribute :account_id
+
+    class << self
+      def url(*params)
+        ["/accounts", *params].join '/'
+      end
+
+      def show_url(*params)
+        ["/account", *params].join '/'
+      end
+    end
+  end
+end

data/lib/conexa/resources/bill.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Conexa
   class Bill  < Model
     def save
-      raise NoMethodError
+      raise NoMethodError, "Bill does not support save"
     end
   end
 end

data/lib/conexa/resources/bill_category.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Conexa
+  # BillCategory resource (Categoria de Despesa)
+  #
+  # @example Find a bill category
+  #   category = Conexa::BillCategory.find(4)
+  #   category.name  # => "Impostos"
+  #
+  # @example List bill categories
+  #   categories = Conexa::BillCategory.all(limit: 50)
+  #
+  # @!attribute [r] bill_category_id
+  #   @return [Integer] Bill category ID (also accessible as #id)
+  # @!attribute [r] name
+  #   @return [String] Category name
+  # @!attribute [r] is_active
+  #   @return [Boolean] Whether the category is active
+  #
+  class BillCategory < Model
+    primary_key_attribute :bill_category_id
+
+    class << self
+      def url(*params)
+        ["/billCategories", *params].join '/'
+      end
+
+      def show_url(*params)
+        ["/billCategory", *params].join '/'
+      end
+    end
+  end
+end

data/lib/conexa/resources/bill_subcategory.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Conexa
+  # BillSubcategory resource (Subcategoria de Despesa)
+  #
+  # @example Find a bill subcategory
+  #   subcategory = Conexa::BillSubcategory.find(29)
+  #   subcategory.name  # => "Taxa de Cartão"
+  #
+  # @example List bill subcategories
+  #   subcategories = Conexa::BillSubcategory.all(limit: 50)
+  #
+  # @!attribute [r] bill_subcategory_id
+  #   @return [Integer] Bill subcategory ID (also accessible as #id)
+  # @!attribute [r] name
+  #   @return [String] Subcategory name
+  # @!attribute [r] bill_category_id
+  #   @return [Integer] Parent bill category ID
+  # @!attribute [r] is_active
+  #   @return [Boolean] Whether the subcategory is active
+  #
+  class BillSubcategory < Model
+    primary_key_attribute :bill_subcategory_id
+
+    class << self
+      def url(*params)
+        ["/billSubcategories", *params].join '/'
+      end
+
+      def show_url(*params)
+        ["/billSubcategory", *params].join '/'
+      end
+    end
+  end
+end