c6_bank 0.2.0

data/lib/c6_bank/configuration.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module C6Bank
+  class Configuration
+    SANDBOX_BASE_URL = "https://baas-api-sandbox.c6bank.info"
+    PRODUCTION_BASE_URL = "https://baas-api.c6bank.info"
+    SANDBOX_BILLING_SCHEME = "21"
+    PRODUCTION_BILLING_SCHEME = "15"
+
+    attr_accessor :client_id,
+                  :client_secret,
+                  :certificate_path,
+                  :private_key_path,
+                  :certificate,
+                  :private_key,
+                  :base_url,
+                  :auth_base_url,
+                  :open_timeout,
+                  :read_timeout,
+                  :write_timeout,
+                  :max_retries,
+                  :token_path,
+                  :boleto_path,
+                  :pix_path,
+                  :dda_path,
+                  :partner_software_name,
+                  :partner_software_version,
+                  :pix_key,
+                  :billing_scheme
+    attr_reader :environment
+
+    def initialize
+      @environment = :sandbox
+      @open_timeout = 10
+      @read_timeout = 30
+      @write_timeout = 30
+      @max_retries = 2
+
+      @token_path  = "/v1/auth"
+      @boleto_path = "/v2/bank_slips"
+      @pix_path    = "/v2/pix"
+      @dda_path    = "/api/v1/pagamentos"
+
+      @auth_base_url = nil
+      @partner_software_name = "c6_bank-gem"
+      @partner_software_version = C6Bank::VERSION
+      @pix_key = nil
+      @billing_scheme = nil
+    end
+
+    def environment=(env)
+      @environment = env.to_sym
+    end
+
+    def sandbox?
+      environment == :sandbox
+    end
+
+    def production?
+      environment == :production
+    end
+
+    def effective_base_url
+      return base_url if base_url
+
+      sandbox? ? SANDBOX_BASE_URL : PRODUCTION_BASE_URL
+    end
+
+    def effective_auth_base_url
+      return auth_base_url if auth_base_url
+
+      effective_base_url
+    end
+
+    def effective_billing_scheme
+      billing_scheme.to_s.empty? ? default_billing_scheme : billing_scheme.to_s
+    end
+
+    def default_billing_scheme
+      production? ? PRODUCTION_BILLING_SCHEME : SANDBOX_BILLING_SCHEME
+    end
+
+    def ssl_certificate
+      return certificate if certificate
+
+      OpenSSL::X509::Certificate.new(File.read(certificate_path)) if certificate_path
+    end
+
+    def ssl_private_key
+      return private_key if private_key
+
+      OpenSSL::PKey::RSA.new(File.read(private_key_path)) if private_key_path
+    end
+
+    def validate!
+      raise C6Bank::ConfigurationError, "client_id and client_secret are required" unless client_id && client_secret
+
+      unless ssl_certificate && ssl_private_key
+        raise C6Bank::ConfigurationError,
+              "Either certificate_path + private_key_path or certificate + private_key must be provided for mTLS"
+      end
+
+      warn_if_certificate_expired!
+    end
+
+    private
+
+    def warn_if_certificate_expired!
+      cert = ssl_certificate
+      expiry = cert.respond_to?(:not_after) ? cert.not_after : nil
+      return unless expiry.is_a?(Time) && expiry < Time.now.utc && expiry.year > 1980
+
+      warn "[c6_bank] mTLS certificate expired on #{expiry}. Replace C6_CERT_PATH / C6_KEY_PATH."
+    rescue OpenSSL::X509::CertificateError, ArgumentError, TypeError
+      nil
+    end
+  end
+end

data/lib/c6_bank/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module C6Bank
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class AuthenticationError < Error; end
+
+  class ApiError < Error
+    attr_reader :status, :body, :response
+
+    def initialize(message = nil, status: nil, body: nil, response: nil)
+      @status = status
+      @body = body
+      @response = response
+      super(message || default_message)
+    end
+
+    private
+
+    def default_message
+      msg = "C6 Bank API error"
+      msg += " (status: #{status})" if status
+      msg += ": #{body}" if body
+      msg
+    end
+  end
+
+  class NotFoundError < ApiError; end
+  class RateLimitError < ApiError; end
+  class ServerError < ApiError; end
+end

data/lib/c6_bank/pix/payload.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module C6Bank
+  module Pix
+    # Normalizes Ruby-friendly hashes into the BACEN Pix JSON contract.
+    module Payload
+      module_function
+
+      TOP_LEVEL_ALIASES = {
+        "pix_key" => "chave",
+        "key" => "chave",
+        "amount" => "valor",
+        "payer" => "devedor",
+        "message" => "solicitacaoPagador",
+        "solicitacao_pagador" => "solicitacaoPagador",
+        "additional_info" => "infoAdicionais",
+        "info_adicionais" => "infoAdicionais"
+      }.freeze
+
+      def immediate(params, default_key:)
+        data = stringify(params)
+        txid = data.delete("txid")
+        apply_aliases!(data)
+        data["chave"] = present(data["chave"]) || present(default_key)
+        require_chave!(data["chave"])
+
+        expiracao = data.delete("expiracao") || data.delete("expiration")
+        calendario = stringify(data["calendario"] || {})
+        calendario["expiracao"] ||= expiracao || 3600
+        data["calendario"] = calendario
+        data["valor"] = normalize_valor(data["valor"])
+        data["devedor"] = normalize_devedor(data["devedor"]) if data["devedor"]
+        [txid, compact(data)]
+      end
+
+      def due(params, default_key:)
+        data = stringify(params)
+        txid = data.delete("txid") || Pix.generate_txid
+        apply_aliases!(data)
+        data["chave"] = present(data["chave"]) || present(default_key)
+        require_chave!(data["chave"])
+
+        due_date = data.delete("dataDeVencimento") || data.delete("due_date") || data.delete("data_vencimento")
+        days_after = data.delete("validadeAposVencimento") ||
+                     data.delete("days_after_due") ||
+                     data.delete("validade_apos_vencimento")
+        calendario = stringify(data["calendario"] || {})
+        calendario["dataDeVencimento"] ||= due_date
+        calendario["validadeAposVencimento"] ||= days_after unless days_after.nil?
+        data["calendario"] = calendario
+        data["valor"] = normalize_valor(data["valor"])
+        data["devedor"] = normalize_devedor(data["devedor"]) if data["devedor"]
+        [txid, compact(data)]
+      end
+
+      def stringify(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, nested), memo| memo[key.to_s] = stringify(nested) }
+        when Array
+          value.map { |item| stringify(item) }
+        else
+          value
+        end
+      end
+
+      def apply_aliases!(data)
+        TOP_LEVEL_ALIASES.each do |from, to|
+          data[to] = data.delete(from) if data.key?(from) && !present(data[to])
+        end
+        data
+      end
+
+      def normalize_valor(value)
+        case value
+        when Hash
+          money = stringify(value)
+          money["original"] = format_money(money["original"]) if money.key?("original")
+          money
+        else
+          { "original" => format_money(value) }
+        end
+      end
+
+      def normalize_devedor(value)
+        return unless value
+
+        person = stringify(value)
+        tax_id = person.delete("tax_id") || person.delete("cpf_cnpj") || person.delete("document")
+        if present(tax_id)
+          digits = tax_id.to_s.gsub(/\D/, "")
+          if digits.length == 14
+            person["cnpj"] ||= digits
+          else
+            person["cpf"] ||= digits
+          end
+        end
+        person
+      end
+
+      def format_money(value)
+        format("%.2f", Float(value))
+      end
+
+      def require_chave!(chave)
+        return if present(chave)
+
+        raise ConfigurationError,
+              "A Pix key is required. Set C6Bank pix_key (C6_PIX_KEY) or pass chave: in the request."
+      end
+
+      def present(value)
+        str = value.to_s.strip
+        str.empty? ? nil : value
+      end
+
+      def compact(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), memo|
+            compacted = compact(nested)
+            memo[key] = compacted unless compacted.nil?
+          end
+        when Array
+          value.map { |item| compact(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/c6_bank/pix.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "pix/payload"
+
+module C6Bank
+  # Helpers for the BACEN Pix API (cob / cobv) exposed by C6 Bank at `/v2/pix`.
+  module Pix
+    module_function
+
+    def generate_txid(length = 32)
+      length = length.clamp(26, 35)
+      SecureRandom.alphanumeric(length)
+    end
+  end
+end

data/lib/c6_bank/resources/base.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module C6Bank
+  module Resources
+    class Base
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      protected
+
+      def request(*args, **kwargs)
+        client.request(*args, **kwargs)
+      end
+
+      # Returns the configured path for this resource.
+      # Resources override #default_path
+      def path
+        config_path = begin
+          client.config.public_send("#{self.class.name.split("::").last.downcase}_path")
+        rescue StandardError
+          nil
+        end
+        config_path || default_path
+      end
+
+      def default_path
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/c6_bank/resources/boleto.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module C6Bank
+  module Resources
+    class Boleto < Base
+      def create(params_or_request)
+        body = payload_from(params_or_request)
+        request(:post, boleto_path, body: body)
+      end
+
+      alias emit create
+      alias issue create
+
+      def find(external_reference_id)
+        request(:get, "#{boleto_path}/#{external_reference_id}")
+      end
+
+      def list(params = {})
+        request(:get, "#{boleto_path}/list", params: stringify(params))
+      end
+
+      def update(external_reference_id, params = {})
+        request(:patch, "#{boleto_path}/#{external_reference_id}", body: stringify(params))
+      end
+
+      def pdf(external_reference_id)
+        # C6 sandbox returns 406 for `Accept: application/pdf` alone and
+        # serves `Content-Type: application/pdf` when Accept is `*/*` or JSON.
+        response = client.request(
+          :get,
+          "#{boleto_path}/#{external_reference_id}/pdf",
+          headers: { "Accept" => "*/*" },
+          raw: true
+        )
+        response.body
+      end
+
+      def cancel(external_reference_id)
+        request(:put, "#{boleto_path}/#{external_reference_id}/cancel")
+      end
+
+      alias baixa cancel
+
+      private
+
+      def boleto_path
+        client.config.boleto_path || "/v2/bank_slips"
+      end
+
+      def payload_from(params_or_request)
+        omit_pix = false
+        body =
+          if params_or_request.is_a?(C6Bank::Boleto::Request)
+            omit_pix = params_or_request.omit_pix?
+            params_or_request.to_h
+          else
+            hash = stringify(params_or_request)
+            omit_pix = hash["pix"] == false || hash["omit_pix"] == true
+            hash.delete("pix") if hash["pix"] == false
+            hash.delete("omit_pix")
+            hash
+          end
+
+        C6Bank::Boleto::Request.apply_defaults(body, client.config, omit_pix: omit_pix)
+      end
+
+      def stringify(value)
+        C6Bank::Pix::Payload.stringify(value)
+      end
+    end
+  end
+end

data/lib/c6_bank/resources/dda.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module C6Bank
+  module Resources
+    # DDA + scheduled payment groups (agendamento de pagamentos).
+    # Covers roteiro section 8.
+    class Dda < Base
+      # 8.1 - Query open DDA boletos for a customer
+      def query_dda(params)
+        request(:get, "#{dda_path}/dda", params: params)
+      end
+
+      # 8.2 - Submit a payment group for consultation
+      def create_payment_group(params)
+        request(:post, "#{dda_path}/grupos", body: params)
+      end
+
+      # Get items of a group
+      def get_group_items(group_id)
+        request(:get, "#{dda_path}/grupos/#{group_id}/itens")
+      end
+
+      # Remove items (list or single)
+      def remove_from_group(group_id, params)
+        request(:delete, "#{dda_path}/grupos/#{group_id}/itens", body: params)
+      end
+
+      # Approve/submit group
+      def approve_group(group_id)
+        request(:post, "#{dda_path}/grupos/#{group_id}/aprovar")
+      end
+
+      private
+
+      def dda_path
+        client.config.dda_path || "/api/v1/pagamentos"
+      end
+    end
+  end
+end

data/lib/c6_bank/resources/pix.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module C6Bank
+  module Resources
+    # BACEN Pix API (C6 Bank) — `/v2/pix`.
+    #
+    # Immediate charges (cob), due-date charges (cobv), received Pix, refunds
+    # and webhook configuration.
+    class Pix < Base
+      def create_immediate_charge(params = {})
+        txid, body = C6Bank::Pix::Payload.immediate(params, default_key: default_pix_key)
+        if txid
+          request(:put, "#{pix_path}/cob/#{txid}", body: body)
+        else
+          request(:post, "#{pix_path}/cob", body: body)
+        end
+      end
+
+      def revise_immediate(txid, params = {})
+        request(:patch, "#{pix_path}/cob/#{txid}", body: stringify_params(params))
+      end
+
+      def find_immediate(txid)
+        request(:get, "#{pix_path}/cob/#{txid}")
+      end
+
+      def list_immediate(params = {})
+        request(:get, "#{pix_path}/cob", params: stringify_params(params))
+      end
+
+      def create_due_charge(params = {})
+        txid, body = C6Bank::Pix::Payload.due(params, default_key: default_pix_key)
+        request(:put, "#{pix_path}/cobv/#{txid}", body: body)
+      end
+
+      def revise_due(txid, params = {})
+        request(:patch, "#{pix_path}/cobv/#{txid}", body: stringify_params(params))
+      end
+
+      def find_due(txid)
+        request(:get, "#{pix_path}/cobv/#{txid}")
+      end
+
+      def list_due(params = {})
+        request(:get, "#{pix_path}/cobv", params: stringify_params(params))
+      end
+
+      def received(e2eid)
+        request(:get, "#{pix_path}/pix/#{e2eid}")
+      end
+
+      def list_received(params = {})
+        request(:get, "#{pix_path}/pix", params: stringify_params(params))
+      end
+
+      def refund(e2eid, id, params = {})
+        request(:put, "#{pix_path}/pix/#{e2eid}/devolucao/#{id}", body: stringify_params(params))
+      end
+
+      def find_refund(e2eid, id)
+        request(:get, "#{pix_path}/pix/#{e2eid}/devolucao/#{id}")
+      end
+
+      def configure_webhook(params = {})
+        chave = webhook_chave(params)
+        url = params[:webhookUrl] || params["webhookUrl"] || params[:webhook_url] ||
+              params["webhook_url"] || params[:url] || params["url"]
+        request(:put, "#{pix_path}/webhook/#{encode_chave(chave)}", body: { "webhookUrl" => url })
+      end
+
+      def webhook(chave = nil)
+        request(:get, "#{pix_path}/webhook/#{encode_chave(webhook_chave(chave: chave))}")
+      end
+
+      def delete_webhook(chave = nil)
+        request(:delete, "#{pix_path}/webhook/#{encode_chave(webhook_chave(chave: chave))}")
+      end
+
+      def list_webhooks(params = {})
+        request(:get, "#{pix_path}/webhook", params: stringify_params(params))
+      end
+
+      private
+
+      def pix_path
+        client.config.pix_path
+      end
+
+      def default_pix_key
+        client.config.pix_key
+      end
+
+      def stringify_params(params)
+        C6Bank::Pix::Payload.stringify(params)
+      end
+
+      def webhook_chave(params = {})
+        params = { chave: params } unless params.is_a?(Hash)
+        chave = params[:chave] || params["chave"] || params[:key] || params["key"] || default_pix_key
+        C6Bank::Pix::Payload.require_chave!(chave)
+        chave
+      end
+
+      def encode_chave(chave)
+        CGI.escapeURIComponent(chave.to_s)
+      end
+    end
+  end
+end

data/lib/c6_bank/resources.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "resources/base"
+require_relative "resources/boleto"
+require_relative "resources/pix"
+require_relative "resources/dda"
+
+module C6Bank
+  module Resources
+  end
+end

data/lib/c6_bank/version.rb

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

data/lib/c6_bank.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "c6_bank/version"
+require_relative "c6_bank/errors"
+require_relative "c6_bank/configuration"
+require_relative "c6_bank/client"
+require_relative "c6_bank/pix"
+require_relative "c6_bank/resources"
+require_relative "c6_bank/boleto/request"
+
+module C6Bank
+  class << self
+    attr_writer :client
+
+    def client
+      @client ||= begin
+        unless @config_block_ran
+          raise ConfigurationError, "C6Bank not configured. Call C6Bank.configure or C6Bank.client= first."
+        end
+
+        build_default_client
+      end
+    end
+
+    def configure
+      config = Configuration.new
+      yield config if block_given?
+      config.validate!
+      @config_block_ran = true
+      @client = Client.new(
+        client_id: config.client_id,
+        client_secret: config.client_secret,
+        certificate: config.ssl_certificate,
+        private_key: config.ssl_private_key,
+        environment: config.environment,
+        base_url: config.base_url,
+        auth_base_url: config.auth_base_url,
+        token_path: config.token_path,
+        boleto_path: config.boleto_path,
+        pix_path: config.pix_path,
+        dda_path: config.dda_path,
+        partner_software_name: config.partner_software_name,
+        partner_software_version: config.partner_software_version,
+        pix_key: config.pix_key,
+        billing_scheme: config.billing_scheme
+      )
+    end
+
+    def from_env(**overrides)
+      @config_block_ran = true
+      @client = Client.from_env(**overrides)
+    end
+
+    def boletos = client.boletos
+    def pix = client.pix
+    def dda = client.dda
+
+    def boleto_request(params = {})
+      Boleto::Request.new(params)
+    end
+
+    private
+
+    def build_default_client
+      raise ConfigurationError, "No global client configured"
+    end
+  end
+end

data/sig/c6_bank.rbs

@@ -0,0 +1,4 @@
+module C6Bank
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end