asaas-sdk 0.1.0

data/lib/asaas/client.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+
+module Asaas
+  class Client
+    RETRY_STATUSES     = [429, 500, 502, 503, 504].freeze
+    IDEMPOTENT_METHODS = %i[post put patch].freeze
+    MAX_LOG_BODY_BYTES = 200
+    SENSITIVE_LOG_KEYS = %w[
+      accesskey
+      accesssecret
+      accesstoken
+      apikey
+      apisecret
+      authkey
+      authenticationtoken
+      authorization
+      authtoken
+      bearertoken
+      clientsecret
+      creditcard
+      creditcardholderinfo
+      creditcardtoken
+      idtoken
+      password
+      privatekey
+      refreshtoken
+      cardnumber
+      creditcardnumber
+      ccv
+      cvv
+      number
+      remoteip
+      secret
+      secretkey
+      sessiontoken
+      token
+      webhooktoken
+    ].freeze
+    HTTP_METHODS = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      put: Net::HTTP::Put,
+      patch: Net::HTTP::Patch,
+      delete: Net::HTTP::Delete
+    }.freeze
+
+    def initialize(config = Asaas.config, api_key: nil)
+      @config  = config
+      @api_key = api_key || config.api_key
+    end
+
+    # @param method  [:get, :post, :put, :patch, :delete]
+    # @param path    [String]
+    # @param params  [Hash]
+    # @param headers [Hash]
+    # @param retryable [Boolean]
+    # @return [Hash]
+    def request(method, path, params: {}, headers: {}, retryable: true, timeout: nil, idempotency_key: nil) # rubocop:disable Metrics/ParameterLists
+      validate_config!
+
+      uri = build_uri(path, method == :get ? params : {})
+      body = method == :get ? {} : params
+      request_idempotency_key = idempotency_key_for(method, idempotency_key)
+      request_headers = build_headers(headers, request_idempotency_key)
+      if explicit_idempotency_key?(method, idempotency_key)
+        replace_idempotency_key(request_headers, request_idempotency_key)
+      end
+      operation = -> { perform(method, uri, body, request_headers, timeout: timeout) }
+
+      retryable ? with_retries(&operation) : operation.call
+    end
+
+    private
+
+    def validate_config!
+      return unless @api_key.nil? || @api_key.empty?
+
+      raise ConfigurationError, "Asaas.api_key is not set. Call Asaas.configure { |c| c.api_key = '...' }"
+    end
+
+    def build_uri(path, query_params = {})
+      uri = URI.parse("#{@config.base_url}#{path}")
+      uri.query = URI.encode_www_form(flatten_params(query_params)) if query_params.any?
+      uri
+    end
+
+    def build_headers(extra = {}, idempotency_key = nil)
+      headers = {
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "access_token" => @api_key,
+        "User-Agent" => "AsaasRuby/#{Asaas::VERSION}"
+      }
+      headers["Idempotency-Key"] = idempotency_key if idempotency_key
+      headers.merge(extra)
+    end
+
+    def idempotency_key_for(method, explicit_key)
+      return unless IDEMPOTENT_METHODS.include?(method)
+      return SecureRandom.uuid if explicit_key.nil?
+      return explicit_key.dup.freeze if explicit_key.is_a?(String) && !explicit_key.strip.empty?
+
+      raise ArgumentError, "idempotency_key must be a non-blank String"
+    end
+
+    def explicit_idempotency_key?(method, key)
+      IDEMPOTENT_METHODS.include?(method) && !key.nil?
+    end
+
+    def replace_idempotency_key(headers, key)
+      headers.delete_if { |name, _| name.to_s.casecmp?("Idempotency-Key") }
+      headers["Idempotency-Key"] = key
+    end
+
+    def perform(method, uri, body, headers, timeout: nil)
+      http              = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl      = uri.scheme == "https"
+      http.read_timeout = timeout || @config.timeout
+      http.open_timeout = timeout || @config.timeout
+
+      req = build_request(method, uri, headers, body)
+
+      log_request(method, uri, body)
+
+      res = begin
+        http.request(req)
+      rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT,
+             Net::OpenTimeout, Net::ReadTimeout, SocketError => e
+        raise ConnectionError, "Network error: #{e.message}"
+      end
+
+      log_response(res)
+      parse_response(res)
+    end
+
+    def build_request(method, uri, headers, body)
+      req = HTTP_METHODS.fetch(method).new(uri.request_uri, headers)
+      encode_body(req, body) if body.any?
+      req
+    end
+
+    def encode_body(req, body)
+      if multipart?(body)
+        req.delete("Content-Type")
+        req.set_form(to_multipart_parts(body), "multipart/form-data")
+      else
+        req.body = JSON.generate(body)
+      end
+    end
+
+    def multipart?(params)
+      params.values.any? { |v| v.respond_to?(:read) }
+    end
+
+    def to_multipart_parts(params)
+      params.map do |k, v|
+        if v.respond_to?(:read)
+          filename = v.respond_to?(:path) ? File.basename(v.path) : k.to_s
+          [k.to_s, v, { filename: filename }]
+        else
+          [k.to_s, v.to_s]
+        end
+      end
+    end
+
+    def parse_response(res)
+      status     = res.code.to_i
+      request_id = res["X-Request-Id"]
+      body       = parse_body(res.body)
+
+      raise Asaas.error_for_status(status, body, request_id) unless (200..299).cover?(status)
+
+      body
+    end
+
+    def parse_body(raw)
+      return {} if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def with_retries
+      attempts = 0
+      begin
+        yield
+      rescue RateLimitError, ServerError, ConnectionError => e
+        attempts += 1
+        if attempts <= @config.max_retries && retryable?(e)
+          sleep(@config.retry_delay * (2**(attempts - 1)))
+          retry
+        end
+        raise
+      end
+    end
+
+    def retryable?(error)
+      case error
+      in ConnectionError | RateLimitError then true
+      in ServerError if RETRY_STATUSES.include?(error.http_status) then true
+      else false
+      end
+    end
+
+    def flatten_params(params, prefix = nil)
+      params.each_with_object({}) do |(k, v), result|
+        key = prefix ? "#{prefix}[#{k}]" : k.to_s
+        case v
+        when Hash  then result.merge!(flatten_params(v, key))
+        when Array then result[key] = v.join(",")
+        else            result[key] = v
+        end
+      end
+    end
+
+    def log_request(method, uri, body)
+      return unless @config.logger
+
+      body_log = if body.none?
+                   ""
+                 elsif multipart?(body)
+                   " [multipart/form-data: #{body.keys.join(", ")}]"
+                 else
+                   " #{sanitize(body).to_json}"
+                 end
+
+      @config.logger.debug("[Asaas] --> #{method.upcase} #{uri}#{body_log}")
+    end
+
+    def log_response(res)
+      return unless @config.logger
+
+      parsed_body = JSON.parse(res.body.to_s)
+      @config.logger.debug("[Asaas] <-- #{res.code} #{bounded_log_json(parsed_body)}")
+    rescue JSON::ParserError
+      @config.logger.debug("[Asaas] <-- #{res.code} #{res.body.to_s.bytesize} bytes")
+    end
+
+    def bounded_log_json(value)
+      sanitized_json = JSON.generate(sanitize(value))
+      return sanitized_json if sanitized_json.bytesize <= MAX_LOG_BODY_BYTES
+
+      JSON.generate("_truncated" => true, "_bytes" => sanitized_json.bytesize)
+    end
+
+    def sanitize(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, nested_value), sanitized|
+          sanitized[key] = sensitive_key?(key) ? "[FILTERED]" : sanitize(nested_value)
+        end
+      when Array
+        value.map { |nested_value| sanitize(nested_value) }
+      else
+        value
+      end
+    end
+
+    def sensitive_key?(key)
+      normalized_key = key.to_s.downcase.gsub(/[^a-z0-9]/, "")
+      SENSITIVE_LOG_KEYS.include?(normalized_key)
+    end
+  end
+end

data/lib/asaas/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Asaas
+  class Configuration
+    PRODUCTION_URL = "https://api.asaas.com/v3"
+    SANDBOX_URL    = "https://sandbox.asaas.com/api/v3"
+
+    DEFAULT_TIMEOUT     = 30
+    DEFAULT_MAX_RETRIES = 2
+    DEFAULT_RETRY_DELAY = 0.5
+
+    attr_accessor :api_key,
+                  :sandbox,
+                  :timeout,
+                  :max_retries,
+                  :retry_delay,
+                  :logger
+
+    def initialize
+      @sandbox     = false
+      @timeout     = DEFAULT_TIMEOUT
+      @max_retries = DEFAULT_MAX_RETRIES
+      @retry_delay = DEFAULT_RETRY_DELAY
+      @logger      = nil
+    end
+
+    def base_url
+      sandbox ? SANDBOX_URL : PRODUCTION_URL
+    end
+  end
+end

data/lib/asaas/errors.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Asaas
+  class AsaasError < StandardError
+    attr_reader :http_status, :http_body, :request_id, :errors
+
+    def initialize(message = nil, http_status: nil, http_body: nil, request_id: nil, errors: nil)
+      super(message)
+      @http_status = http_status
+      @http_body   = http_body
+      @request_id  = request_id
+      @errors      = errors || []
+    end
+
+    def to_s
+      msg = super
+      msg += " (status=#{http_status})" if http_status
+      msg += " [request_id=#{request_id}]" if request_id
+      msg
+    end
+  end
+
+  # 400
+  class InvalidRequestError      < AsaasError; end
+  # 401
+  class AuthenticationError      < AsaasError; end
+  # 403
+  class PermissionError          < AsaasError; end
+  # 404
+  class NotFoundError            < AsaasError; end
+  # 409
+  class ConflictError            < AsaasError; end
+  # 422
+  class UnprocessableEntityError < AsaasError; end
+  # 429
+  class RateLimitError           < AsaasError; end
+  # 5xx
+  class ServerError              < AsaasError; end
+  # network
+  class ConnectionError          < AsaasError; end
+  # sdk config
+  class ConfigurationError       < AsaasError; end
+  # webhook token missing or mismatched
+  class WebhookVerificationError < AsaasError; end
+  # webhook payload is not valid JSON
+  class InvalidPayloadError      < AsaasError; end
+
+  def self.error_for_status(http_status, http_body, request_id)
+    message = extract_message(http_body)
+    errors = extract_errors(http_body)
+    kwargs = { http_status:, http_body:, request_id:, errors: }
+
+    case http_status
+    when 400 then InvalidRequestError.new(message, **kwargs)
+    when 401 then AuthenticationError.new(message, **kwargs)
+    when 403 then PermissionError.new(message, **kwargs)
+    when 404 then NotFoundError.new(message, **kwargs)
+    when 409 then ConflictError.new(message, **kwargs)
+    when 422 then UnprocessableEntityError.new(message, **kwargs)
+    when 429 then RateLimitError.new(message, **kwargs)
+    when 500..599 then ServerError.new(message, **kwargs)
+    else AsaasError.new(message, **kwargs)
+    end
+  end
+
+  def self.extract_message(body)
+    return "Unknown error" unless body.is_a?(Hash)
+
+    if body["errors"].is_a?(Array) && body["errors"].any?
+      body["errors"].filter_map { _1["description"] }.join("; ")
+    else
+      body["message"] || "Unknown error"
+    end
+  end
+  private_class_method :extract_message
+
+  def self.extract_errors(body)
+    return [] unless body.is_a?(Hash) && body["errors"].is_a?(Array)
+
+    body["errors"]
+  end
+  private_class_method :extract_errors
+end

data/lib/asaas/list_object.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Asaas
+  class ListObject
+    include Enumerable
+
+    attr_reader :data, :has_more, :total_count, :limit, :offset
+
+    def initialize(attrs, client:, path:, params: {})
+      @data        = Array(attrs["data"]).map { AsaasObject.construct_from(_1) }
+      @has_more    = attrs["hasMore"] || false
+      @total_count = attrs["totalCount"]
+      @limit       = attrs["limit"]
+      @offset      = attrs["offset"] || 0
+      @client      = client
+      @path        = path
+      @params      = params
+    end
+
+    def each(&block)
+      @data.each(&block)
+    end
+
+    def next_page
+      return nil unless @has_more
+
+      next_params = @params.merge("offset" => @offset + @limit, "limit" => @limit)
+      raw = @client.request(:get, @path, params: next_params)
+      self.class.new(raw, client: @client, path: @path, params: next_params)
+    end
+
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block
+
+      page = self
+      loop do
+        page.each(&block)
+        break unless page.has_more
+
+        page = page.next_page
+      end
+    end
+
+    def self.construct_from(attrs, client:, path:, params: {})
+      new(attrs, client: client, path: path, params: params)
+    end
+
+    def inspect
+      "#<#{self.class} total_count=#{@total_count} has_more=#{@has_more} data=#{@data.inspect}>"
+    end
+  end
+end

data/lib/asaas/resources/anticipation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    class Anticipation < Base
+      def self.resource_path = "/anticipations"
+
+      def self.simulate(params = {}, opts = {})
+        response = client(opts).request(:post, "#{resource_path}/simulate", params: params)
+        AsaasObject.construct_from(response)
+      end
+    end
+  end
+end

data/lib/asaas/resources/base.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    class Base
+      extend HasClient
+
+      def self.resource_path
+        raise NotImplementedError, "#{name} must define resource_path"
+      end
+
+      def self.create(params = {}, opts = {})
+        response = client(opts).request(
+          :post,
+          resource_path,
+          params: params,
+          retryable: opts.fetch(:retryable, true),
+          timeout: opts[:timeout],
+          idempotency_key: opts[:idempotency_key]
+        )
+        AsaasObject.construct_from(response)
+      end
+
+      def self.retrieve(id, opts = {})
+        response = client(opts).request(
+          :get,
+          "#{resource_path}/#{id}",
+          retryable: opts.fetch(:retryable, true),
+          timeout: opts[:timeout]
+        )
+        AsaasObject.construct_from(response)
+      end
+
+      def self.update(id, params = {}, opts = {})
+        response = client(opts).request(:put, "#{resource_path}/#{id}", params: params)
+        AsaasObject.construct_from(response)
+      end
+
+      def self.delete(id, opts = {})
+        response = client(opts).request(:delete, "#{resource_path}/#{id}")
+        AsaasObject.construct_from(response)
+      end
+
+      def self.list(params = {}, opts = {})
+        response = client(opts).request(:get, resource_path, params: params)
+        ListObject.construct_from(response, client: client(opts), path: resource_path, params: params)
+      end
+    end
+  end
+end

data/lib/asaas/resources/bill_payment.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    class BillPayment < Base
+      def self.resource_path = "/bill"
+    end
+  end
+end

data/lib/asaas/resources/chargeback.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    class Chargeback < Base
+      def self.resource_path = "/chargebacks"
+
+      def self.dispute(id, params = {}, opts = {})
+        response = client(opts).request(:post, "#{resource_path}/#{id}/disputes", params: params)
+        AsaasObject.construct_from(response)
+      end
+    end
+  end
+end

data/lib/asaas/resources/checkout.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    class Checkout < Base
+      def self.resource_path = "/checkouts"
+    end
+  end
+end

data/lib/asaas/resources/credit_card.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    class CreditCard < Base
+      def self.resource_path = "/creditCard"
+
+      def self.tokenize(params = {}, opts = {})
+        response = client(opts).request(
+          :post,
+          "#{resource_path}/tokenizeCreditCard",
+          params: params,
+          retryable: opts.fetch(:retryable, false),
+          timeout: opts[:timeout]
+        )
+        AsaasObject.construct_from(response)
+      end
+    end
+  end
+end

data/lib/asaas/resources/customer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    class Customer < Base
+      def self.resource_path = "/customers"
+
+      def self.restore(id, opts = {})
+        response = client(opts).request(:post, "#{resource_path}/#{id}/restore")
+        AsaasObject.construct_from(response)
+      end
+
+      def self.notifications(id, params = {}, opts = {})
+        path = "#{resource_path}/#{id}/notifications"
+        response = client(opts).request(:get, path, params: params)
+        ListObject.construct_from(response, client: client(opts), path: path, params: params)
+      end
+    end
+  end
+end

data/lib/asaas/resources/document.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    # KYC documents for the authenticated (sub)account: /myAccount/documents.
+    # All calls act on the account that owns the api_key, so pass the
+    # subaccount's own key per call: Document.pending(api_key: "aact_sub_key").
+    class Document
+      extend HasClient
+
+      def self.resource_path = "/myAccount/documents"
+
+      # Lists pending document groups (each with its onboardingUrl and any
+      # files already sent). Returns an AsaasObject with a `data` array.
+      def self.pending(opts = {})
+        response = client(opts).request(:get, resource_path)
+        AsaasObject.construct_from(response)
+      end
+
+      # Uploads a file to a document group (multipart). `file` is any IO that
+      # responds to #read; `type` is the Asaas document type (e.g. "IDENTIFICATION").
+      def self.send_document(group_id, file:, type:, **opts)
+        params = { documentFile: file, type: type }
+        response = client(opts).request(:post, "#{resource_path}/#{group_id}", params: params)
+        AsaasObject.construct_from(response)
+      end
+
+      # Removes a previously sent file by its file id.
+      def self.delete_file(file_id, opts = {})
+        response = client(opts).request(:delete, "#{resource_path}/files/#{file_id}")
+        AsaasObject.construct_from(response)
+      end
+    end
+  end
+end

data/lib/asaas/resources/dunning.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    class Dunning < Base
+      def self.resource_path = "/paymentDunnings"
+
+      def self.resend_documents(id, opts = {})
+        response = client(opts).request(:post, "#{resource_path}/#{id}/documents")
+        AsaasObject.construct_from(response)
+      end
+    end
+  end
+end

data/lib/asaas/resources/finance.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    class Finance
+      extend HasClient
+
+      def self.balance(opts = {})
+        response = client(opts).request(:get, "/finance/balance")
+        AsaasObject.construct_from(response)
+      end
+
+      def self.statistics(params = {}, opts = {})
+        response = client(opts).request(:get, "/finance/payment/statistics", params: params)
+        AsaasObject.construct_from(response)
+      end
+
+      def self.extract(params = {}, opts = {})
+        path = "/financialTransactions"
+        response = client(opts).request(:get, path, params: params)
+        ListObject.construct_from(response, client: client(opts), path: path, params: params)
+      end
+    end
+  end
+end

data/lib/asaas/resources/has_client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    module HasClient
+      def self.extended(base)
+        base.private_class_method(:client)
+      end
+
+      def client(opts = {})
+        Client.new(api_key: opts[:api_key])
+      end
+    end
+  end
+end

data/lib/asaas/resources/installment.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Asaas
+  module Resources
+    class Installment < Base
+      def self.resource_path = "/installments"
+
+      def self.update_splits(id, params = {}, opts = {})
+        response = client(opts).request(:put, "#{resource_path}/#{id}/splits", params: params)
+        AsaasObject.construct_from(response)
+      end
+    end
+  end
+end