conexa 0.0.6 → 0.0.8

data/lib/conexa/authenticator.rb

@@ -2,6 +2,8 @@ require 'jwt'
 
 
 module Conexa
+  # Valid client types for authentication
+  CLIENT_TYPES = [:pdv, :e_comerce].freeze
   #
   # Class to hold client authetication data
   #

data/lib/conexa/model.rb

@@ -1,5 +1,53 @@
 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
+  #   customer.is_active      # => true
+  #
+  # The API returns camelCase (companyId), ConexaObject converts to snake_case
+  # (company_id), and method_missing handles the lookup transparently.
+  #
+  # == Primary Key
+  #
+  # Each resource needs primary_key_attribute for :id alias and operations
+  # that require 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)
+  #
+  # == Why explicit primary_key_attribute?
+  #
+  # The default primary_key_name generates "classname_id" (e.g., "charge_id"),
+  # but compound names like RecurringSale would generate "recurringsale_id"
+  # 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
@@ -29,7 +77,7 @@ module Conexa
     end
 
     def primary_key_name
-      class_name.downcase + "_id"
+      Util.to_snake_case(class_name) + "_id"
     end
 
     def class_name
@@ -39,6 +87,7 @@ 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)
+      self
     end
 
     class << self
@@ -68,7 +117,9 @@ module Conexa
       alias :where :all
 
       def destroy id
-        self.new(id: id).destroy
+        instance = self.new
+        instance.set_primary_key(id)
+        instance.destroy
       end
 
       def url(*params)

data/lib/conexa/object.rb

@@ -1,4 +1,21 @@
 module Conexa
+  # Base class for all Conexa objects with dynamic attribute access
+  #
+  # == Attribute Access via method_missing
+  #
+  # Attributes can be accessed using either snake_case or camelCase:
+  #   customer.company_id  # => 3
+  #   customer.companyId   # => 3 (converted to snake_case internally)
+  #
+  # The API returns camelCase attributes which are stored as snake_case.
+  # method_missing automatically converts any camelCase calls to snake_case.
+  #
+  # == Attribute Assignment
+  #
+  # Attributes can be set using snake_case:
+  #   customer.name = "New Name"
+  #   customer.save
+  #
   class ConexaObject
     attr_reader :attributes
 

data/lib/conexa/resources/address.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Conexa
+  # Represents an address object (embedded in Customer, etc.)
+  # Not a standalone API resource - used for serialization/deserialization
+  class Address < ConexaObject
+    # @return [String, nil] CEP/ZIP code
+    # @return [String, nil] Street name
+    # @return [String, nil] Street number
+    # @return [String, nil] Neighborhood
+    # @return [String, nil] City
+    # @return [String, nil] State abbreviation (UF)
+    # @return [String, nil] Country (for foreigners)
+    # @return [String, nil] Additional details (complement)
+  end
+end

data/lib/conexa/resources/auth.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Conexa
+  # Authentication resource for username/password authentication
+  # 
+  # @example Authenticate with credentials
+  #   auth = Conexa::Auth.login(username: 'admin', password: 'secret')
+  #   auth.access_token  # => "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
+  #   auth.expires_in    # => 28800
+  #
+  # @note For most cases, use Application Token instead (configured in Conexa.configure)
+  class Auth < ConexaObject
+    class << self
+      # Authenticate with username and password
+      # 
+      # @param username [String] Login username (admin or employee email)
+      # @param password [String] Password
+      # @return [Auth] Authentication result with access_token
+      # @raise [Conexa::AuthenticationError] if credentials are invalid
+      #
+      # @example
+      #   auth = Conexa::Auth.login(username: 'admin', password: 'mypassword')
+      #   # Use the token for subsequent requests
+      #   Conexa.configure { |c| c.api_token = auth.access_token }
+      def login(username:, password:)
+        Conexa::Request.auth('/auth', params: {
+          username: username,
+          password: password
+        }).call('auth')
+      end
+
+      alias_method :authenticate, :login
+    end
+
+    # All attributes (user, token_type, access_token, expires_in) 
+    # are accessible via method_missing
+  end
+end

data/lib/conexa/resources/charge.rb

@@ -1,31 +1,106 @@
+# frozen_string_literal: true
+
 module Conexa
+  # Charge resource for billing/invoices
+  #
+  # @example Retrieve a charge
+  #   charge = Conexa::Charge.find(789)
+  #   charge.status  # => "pending"
+  #
+  # @example List charges
+  #   charges = Conexa::Charge.all(customer_id: [127], status: 'pending')
+  #
+  # @example Settle (pay) a charge
+  #   Conexa::Charge.settle(789)
+  #
+  # @!attribute [r] charge_id
+  #   @return [Integer] Charge ID (also accessible as #id)
+  # @!attribute [r] customer_id
+  #   @return [Integer] Customer ID
+  # @!attribute [r] status
+  #   @return [String] Status: pending, paid, overdue, cancelled
+  # @!attribute [r] amount
+  #   @return [Float] Charge amount
+  # @!attribute [r] due_date
+  #   @return [String] Due date
+  # @!attribute [r] paid_at
+  #   @return [String, nil] Payment date
+  #
   class Charge < Model
-    # Settle (pay) a charge
-    # @param params [Hash] optional parameters (e.g., payment details)
+    primary_key_attribute :charge_id
+
+    # Check if charge is paid
+    # @return [Boolean]
+    def paid?
+      status == 'paid'
+    end
+
+    # Check if charge is pending
+    # @return [Boolean]
+    def pending?
+      status == 'pending'
+    end
+
+    # Check if charge is overdue
+    # @return [Boolean]
+    def overdue?
+      status == 'overdue'
+    end
+
+    # Settle (pay) this charge
+    # @param params [Hash] optional payment details
     # @return [self]
     def settle(params = {})
       Conexa::Request.post(self.class.show_url("settle", primary_key), params: params).call(class_name)
       self
     end
 
-    # Get PIX QR Code for the charge
-    # @return [ConexaObject] PIX data including QR code
+    # Get PIX QR Code for this charge
+    # @return [ConexaObject] PIX data including qr_code and qr_code_base64
     def pix
       Conexa::Request.get(self.class.show_url("pix", primary_key)).call("pix")
     end
 
+    # Cancel this charge
+    # @return [self]
+    def cancel
+      Conexa::Request.post(self.class.show_url("cancel", primary_key)).call(class_name)
+      self
+    end
+
+    # Send charge notification by email
+    # @return [self]
+    def send_email
+      Conexa::Request.post(self.class.show_url("sendEmail", primary_key)).call(class_name)
+      self
+    end
+
     class << self
       # Settle a charge by ID
       # @param id [Integer, String] charge ID
-      # @param params [Hash] optional parameters
+      # @param params [Hash] optional payment details
       # @return [Charge]
       def settle(id, params = {})
         find(id).settle(params)
       end
 
-      # Get PIX QR Code for a charge by ID
+      # Cancel a charge by ID
+      # @param id [Integer, String] charge ID
+      # @return [Charge]
+      def cancel(id)
+        find(id).cancel
+      end
+
+      # Send email for a charge by ID
+      # @param id [Integer, String] charge ID
+      # @return [Charge]
+      def send_email(id)
+        find(id).send_email
+      end
+
+      # Get PIX for a charge by ID
       # @param id [Integer, String] charge ID
-      # @return [ConexaObject] PIX data including QR code
+      # @return [ConexaObject]
       def pix(id)
         find(id).pix
       end

data/lib/conexa/resources/contract.rb

@@ -1,7 +1,55 @@
+# frozen_string_literal: true
+
 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
+  #   )
+  #
+  # @example End a contract
+  #   Conexa::Contract.end_contract(456, end_date: '2024-12-31')
+  #
+  # @!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] 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
+  #
   class Contract < Model
-    # End/terminate a contract
-    # @param params [Hash] optional parameters (e.g., endDate, reason)
+    primary_key_attribute :contract_id
+
+    # Check if contract is active
+    # @return [Boolean]
+    def active?
+      status == 'active'
+    end
+
+    # Check if contract is cancelled/ended
+    # @return [Boolean]
+    def ended?
+      status == 'ended' || status == 'cancelled'
+    end
+
+    # End/terminate this contract
+    # @param params [Hash] options including :end_date, :reason
     # @return [self]
     def end_contract(params = {})
       Conexa::Request.post(self.class.show_url("end", primary_key), params: params).call(class_name)
@@ -11,11 +59,18 @@ module Conexa
     class << self
       # End a contract by ID
       # @param id [Integer, String] contract ID
-      # @param params [Hash] optional parameters (e.g., endDate, reason)
+      # @param params [Hash] options including :end_date, :reason
       # @return [Contract]
       def end_contract(id, params = {})
         find(id).end_contract(params)
       end
+
+      # Create contract with custom product items
+      # @param params [Hash] contract params including :items array
+      # @return [Contract]
+      def create_with_products(params = {})
+        create(params)
+      end
     end
   end
 end

data/lib/conexa/resources/credit_card.rb

@@ -1,5 +1,7 @@
 module Conexa
   class CreditCard < Model
+    primary_key_attribute :credit_card_id
+
     class << self
       def url(*params)
         ["/creditCard", *params].join '/'

data/lib/conexa/resources/customer.rb

@@ -1,5 +1,97 @@
+# frozen_string_literal: true
+
 module Conexa
-  class Customer  < Model
+  # Customer resource for managing clients in Conexa
+  #
+  # @example Create a customer (Legal Person - PJ)
+  #   customer = Conexa::Customer.create(
+  #     company_id: 3,
+  #     name: 'Empresa ABC Ltda',
+  #     legal_person: { cnpj: '99.557.155/0001-90' }
+  #   )
+  #
+  # @example Retrieve a customer
+  #   customer = Conexa::Customer.find(127)
+  #   customer.name  # => "Empresa ABC Ltda"
+  #
+  # @example List customers
+  #   customers = Conexa::Customer.all(company_id: [3], is_active: true)
+  #
+  # @!attribute [r] customer_id
+  #   @return [Integer] Customer ID (also accessible as #id)
+  # @!attribute [r] company_id
+  #   @return [Integer] Company/Unit ID
+  # @!attribute [r] name
+  #   @return [String] Customer name
+  # @!attribute [r] trade_name
+  #   @return [String, nil] Trade name
+  # @!attribute [r] has_login_access
+  #   @return [Boolean] Whether customer has login access
+  # @!attribute [r] is_active
+  #   @return [Boolean] Whether customer is active
+  # @!attribute [r] is_blocked
+  #   @return [Boolean] Whether customer is blocked
+  # @!attribute [r] is_juridical_person
+  #   @return [Boolean] Whether customer is a legal person (PJ)
+  # @!attribute [r] is_foreign
+  #   @return [Boolean] Whether customer is a foreigner
+  # @!attribute [r] legal_person
+  #   @return [Hash, nil] Legal person data (cnpj, foundation_date, etc.)
+  # @!attribute [r] natural_person
+  #   @return [Hash, nil] Natural person data (cpf, birth_date, etc.)
+  # @!attribute [r] created_at
+  #   @return [String, nil] Created at timestamp (W3C format)
+  #
+  class Customer < Model
+    primary_key_attribute :customer_id
+
+    # @return [Array<String>] Phone numbers (empty array if null)
+    def phones
+      @attributes['phones'] || []
+    end
+
+    # @return [Array<String>] Message emails (empty array if null)
+    def emails_message
+      @attributes['emails_message'] || []
+    end
+
+    # @return [Array<String>] Financial emails (empty array if null)
+    def emails_financial_messages
+      @attributes['emails_financial_messages'] || []
+    end
+
+    # @return [Array<Integer>] Tag IDs (empty array if null)
+    def tags_id
+      @attributes['tags_id'] || []
+    end
+
+    # @return [Address, nil] Customer address
+    def address
+      return nil unless @attributes['address']
+      Address.new(@attributes['address'])
+    end
+
+    class << self
+      # List persons (requesters) for a customer
+      # @param customer_id [Integer] Customer ID
+      # @return [Result] List of persons
+      def persons(customer_id)
+        Conexa::Person.all(customer_id: customer_id)
+      end
+
+      # List contracts for a customer
+      # @param customer_id [Integer] Customer ID
+      # @return [Result] List of contracts
+      def contracts(customer_id)
+        Conexa::Contract.all(customer_id: [customer_id])
+      end
 
+      # List charges for a customer
+      # @param customer_id [Integer] Customer ID
+      # @return [Result] List of charges
+      def charges(customer_id)
+        Conexa::Charge.all(customer_id: [customer_id])
+      end
+    end
   end
 end

data/lib/conexa/resources/invoicing_method.rb

@@ -1,5 +1,7 @@
 module Conexa
   class InvoicingMethod < Model
+    primary_key_attribute :invoicing_method_id
+
     class << self
       def url(*params)
         ["/invoicingMethods", *params].join '/'

data/lib/conexa/resources/person.rb

@@ -1,18 +1,4 @@
 module Conexa
   class Person < Model
-    class << self
-      def all(*args, **params)
-        raise NoMethodError
-      end
-
-      def find_by_id(id, **options)
-        raise NoMethodError
-      end
-
-
-      def find_by(params = Hash.new, page = nil, size = nil)
-        raise NoMethodError
-      end
-    end
   end
 end

data/lib/conexa/resources/recurring_sale.rb

@@ -1,5 +1,7 @@
 module Conexa
   class RecurringSale < Model
+    primary_key_attribute :recurring_sale_id
+
     # End/terminate a recurring sale
     # @param params [Hash] optional parameters (e.g., endDate)
     # @return [self]

data/lib/conexa/resources/sale.rb

@@ -1,4 +1,78 @@
+# frozen_string_literal: true
+
 module Conexa
-  class Sale  < Model
+  # Sale resource for one-time sales
+  #
+  # @example Create a sale
+  #   sale = Conexa::Sale.create(
+  #     customer_id: 450,
+  #     product_id: 2521,
+  #     quantity: 1,
+  #     amount: 80.99
+  #   )
+  #
+  # @example List sales
+  #   sales = Conexa::Sale.all(customer_id: [450], status: 'notBilled')
+  #
+  # @!attribute [r] sale_id
+  #   @return [Integer] Sale ID (also accessible as #id)
+  # @!attribute [r] customer_id
+  #   @return [Integer] Customer ID
+  # @!attribute [r] requester_id
+  #   @return [Integer, nil] Requester ID
+  # @!attribute [r] product_id
+  #   @return [Integer] Product ID
+  # @!attribute [r] seller_id
+  #   @return [Integer, nil] Seller (user) ID
+  # @!attribute [r] status
+  #   @return [String] Status: paid, billed, cancelled, notBilled, 
+  #     deductedFromQuota, billedCancelled, billedNegociated, partiallyPaid
+  # @!attribute [r] quantity
+  #   @return [Integer] Quantity
+  # @!attribute [r] amount
+  #   @return [Float] Final amount
+  # @!attribute [r] original_amount
+  #   @return [Float] Original amount before discount
+  # @!attribute [r] discount_value
+  #   @return [Float] Discount value
+  # @!attribute [r] reference_date
+  #   @return [String] Reference date (W3C format)
+  # @!attribute [r] notes
+  #   @return [String, nil] Notes
+  # @!attribute [r] created_at
+  #   @return [String, nil] Created at timestamp
+  # @!attribute [r] updated_at
+  #   @return [String] Updated at timestamp
+  #
+  class Sale < Model
+    primary_key_attribute :sale_id
+
+    # Check if sale is billed
+    # @return [Boolean]
+    def billed?
+      status == 'billed'
+    end
+
+    # Check if sale is paid
+    # @return [Boolean]
+    def paid?
+      status == 'paid'
+    end
+
+    # Check if sale can be edited
+    # @return [Boolean]
+    def editable?
+      status == 'notBilled'
+    end
+
+    class << self
+      def url(*params)
+        ["/sales", *params].join '/'
+      end
+
+      def show_url(*params)
+        ["/sale", *params].join '/'
+      end
+    end
   end
 end

data/lib/conexa/version.rb

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

data/lib/conexa.rb

@@ -10,6 +10,7 @@ require_relative "conexa/errors"
 require_relative "conexa/util"
 require_relative "conexa/configuration"
 require_relative "conexa/order_commom"
+require_relative "conexa/token_manager"
 
 
 Dir[File.expand_path('../conexa/resources/*.rb', __FILE__)].map do |path|

data/scripts/extract_fixtures.rb

@@ -0,0 +1,35 @@
+require 'json'
+
+collection = JSON.parse(File.read('docs/postman-collection.json'))
+
+fixtures_dir = 'spec/fixtures'
+Dir.mkdir(fixtures_dir) unless Dir.exist?(fixtures_dir)
+
+count = 0
+
+collection['item'].each do |section|
+  section_name = section['name'].downcase.gsub(' ', '_').gsub(/[^a-z0-9_]/, '')
+  next if section_name.include?('desenvolvimento')
+  
+  (section['item'] || []).each do |endpoint|
+    method = endpoint.dig('request', 'method') || 'UNKNOWN'
+    responses = endpoint['response'] || []
+    
+    responses.each_with_index do |resp, idx|
+      next unless resp['code'] && resp['code'] < 300
+      next unless resp['body']
+      
+      begin
+        body = JSON.parse(resp['body'])
+        key = "#{section_name}_#{method.downcase}_#{idx}"
+        File.write("#{fixtures_dir}/#{key}.json", JSON.pretty_generate(body))
+        puts "Created: #{key}.json"
+        count += 1
+      rescue JSON::ParserError
+        # skip
+      end
+    end
+  end
+end
+
+puts "\nTotal: #{count} fixtures"