raims 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b8c698e580993846ff354fa3a7a2a3d69dac36cc8ca823cdf3d8a3faebad965
+  data.tar.gz: 590d6014a3faaa756080ac1f3f2fd574171583b7d58fddaa95d9bda808c3ee63
+SHA512:
+  metadata.gz: 0df5664458e513b9a71fe88f9161578dd98bad479115b78682bfd3acdb96126d48a42add8ffdf5f6d39f83230b1c15616e1cad64e6d2744b163811915bf6be4c
+  data.tar.gz: ac7091fdbb2c8be93b61e742ac2111afff4a2aa5b663a7184a90ed4901e155edbb595d95c29af13afc6c9731be4da8b38b3175cf5ed256e70bb6f127ef0ca725

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raims
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,130 @@
+# Raims Ruby
+
+Official Ruby SDK for the Raims public API.
+
+Use resource services, read-only response objects, cursor pagination, structured
+errors, and webhook signature verification in server applications. Requires
+Ruby 3.3 or later.
+
+## Installation
+
+Install the [`raims` gem](https://rubygems.org/gems/raims) from RubyGems:
+
+```sh
+gem install raims
+```
+
+For a Bundler application, add the gem to your `Gemfile`:
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'raims'
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+Load the SDK with `require 'raims'`. Keep your application's `Gemfile.lock`
+under version control to retain its resolved dependency versions.
+
+The [GitHub releases](https://github.com/raimshq/raims-ruby/releases/latest)
+also provide `raims.gem` and `SHA256SUMS`. See
+[installation and updates](docs/installation.md) for verified GitHub downloads
+and updating an existing installation.
+
+## First request
+
+```ruby
+require 'raims'
+
+Raims::RaimsClient.open(ENV.fetch('RAIMS_API_KEY')) do |raims|
+  customers = raims.customers.list({page_size: 20})
+  customers.each do |customer|
+    process_customer(customer.id)
+  end
+end
+```
+
+`process_customer` represents your application's processing. The base URL is
+`https://api.raims.com` for both Sandbox and Production. The key determines
+the company, environment, and permissions. Keep it on the server, outside
+source control and logs.
+
+## Create a charge
+
+Define and persist `customer_id`, `due_date`, and `order_idempotency_key` for
+the order before sending the request. Amounts use integer cents: `15000`
+represents BRL 150.00. The due date uses UTC Unix seconds.
+
+```ruby
+raims = Raims::RaimsClient.new(ENV.fetch('RAIMS_API_KEY'))
+
+begin
+  charge = raims.charges.create(
+    {customer_id: customer_id, amount_cents: 15000, due_date: due_date,
+     title: 'Order 1234'},
+    {idempotency_key: order_idempotency_key}
+  )
+  request_id = charge.last_response.request_id
+ensure
+  raims.close
+end
+```
+
+The SDK does not generate idempotency keys or retry writes automatically.
+After losing a response, keep the same key and parameters and follow the
+endpoint's recovery rules. HTTP `202` means processing is pending; retrieve
+the resource to follow the result.
+
+## Pagination
+
+```ruby
+Raims::RaimsClient.open(ENV.fetch('RAIMS_API_KEY')) do |raims|
+  raims.customers.list({page_size: 50}).auto_paging_each do |customer|
+    process_customer(customer.id)
+  end
+end
+```
+
+`each` reads only the current page. `auto_paging_each` fetches further pages
+as needed and preserves filters and request options. `next_page` and
+`previous_page` provide explicit navigation. Use `auto_paging_to_a(limit)`
+to collect a bounded number of items.
+
+## Services
+
+| Property | Resources |
+| --- | --- |
+| `accounts` | Account context, number, fees, and checkout settings |
+| `balances` | Balance and forecast |
+| `customers` | Customer creation, retrieval, updates, and deletion |
+| `charges` | Charges, payment details, documents, and charge refunds |
+| `payment_links` | Payment links and email delivery requests |
+| `refunds` | Refunds and receipts |
+| `disputes` | Disputes |
+| `statements` | Account statements |
+| `withdrawals` | Withdrawals, limits, summary, and automatic settings |
+| `withdrawal_destinations` | Withdrawal destinations |
+| `webhooks` | Registration, health, pause, test, and secret rotation |
+| `webhook_event_types` | Available event types |
+| `simulations.charges` | Charge simulations with a Sandbox key |
+| `simulations.refunds` | Refund simulations with a Sandbox key |
+
+Services expose methods such as `create`, `retrieve`, `update`, `delete`, and
+`list` according to the public contract. See the [method reference](docs/reference.md).
+
+## Documentation
+
+- [Installation and updates](docs/installation.md)
+- [Configuration, responses, and documents](docs/usage.md)
+- [Pagination](docs/pagination.md)
+- [Errors, idempotency, and retries](docs/errors-and-retries.md)
+- [Receiving webhooks](docs/webhooks.md)
+- [Contributing](CONTRIBUTING.md) and [security](SECURITY.md)
+- [Public API](https://docs.raims.com/en/api)
+
+Distributed under the [MIT license](LICENSE).

data/lib/raims/api_list.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Raims
+  class ApiList < ApiResource
+    include Enumerable
+
+    def initialize(resource, client:, operation_id:, path_params:, params:, options:)
+      @client, @operation_id, @options = client, operation_id, options
+      @path_params = Util.deep_freeze(Util.json_value(path_params))
+      @params = Util.deep_freeze(Util.json_value(params))
+      super(resource.instance_variable_get(:@data), last_response: resource.last_response)
+    end
+
+    def list
+      self['list']
+    end
+
+    def page
+      self['page']
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+      list.each(&block)
+    end
+
+    def next_page
+      load_page(true)
+    end
+
+    def to_h
+      ApiResource.instance_method(:to_h).bind_call(self)
+    end
+    alias to_hash to_h
+
+    def previous_page
+      load_page(false)
+    end
+
+    def auto_paging_each
+      return enum_for(:auto_paging_each) unless block_given?
+      current = self
+      seen = Set.new
+      seen.add(@params['after']) if @params['after']
+      loop do
+        current.each { |item| yield item }
+        params = current.send(:navigation, true)
+        return self unless params
+        cursor = params.fetch('after')
+        if seen.include?(cursor)
+          raise UnexpectedResponseError.new('Pagination returned a repeated cursor.', last_response: current.last_response)
+        end
+        following = current.next_page
+        seen.add(cursor)
+        current = following
+      end
+    end
+
+    def auto_paging_to_a(limit)
+      raise ArgumentError, 'limit must be a non-negative integer.' unless limit.is_a?(Integer) && limit >= 0
+      return [] if limit.zero?
+      result = []
+      auto_paging_each do |item|
+        result << item
+        break if result.length >= limit
+      end
+      result
+    end
+
+    def inspect
+      "#<#{self.class} items=#{list.length}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def navigation(forward)
+      flag, cursor_key, key, opposite = forward ? %w[has_next next_after after before] : %w[has_previous previous_before before after]
+      return nil unless page[flag]
+      cursor = page[cursor_key]
+      unless cursor.is_a?(String) && !cursor.empty? && cursor != @params[key]
+        raise UnexpectedResponseError.new('Pagination returned a missing or repeated cursor.', last_response: last_response)
+      end
+      result = @params.dup
+      result.delete(opposite)
+      result[key] = cursor
+      result
+    end
+
+    def load_page(forward)
+      params = navigation(forward)
+      return nil unless params
+      @client.request(@operation_id, path_params: @path_params, params: params, options: @options)
+    end
+  end
+end

data/lib/raims/api_resource.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Raims
+  class ApiResource
+    attr_reader :last_response
+
+    def initialize(data = {}, last_response: nil)
+      @data = Util.deep_freeze(data.dup)
+      @last_response = last_response
+      freeze
+    end
+
+    def [](key)
+      @data[key.to_s]
+    end
+
+    def key?(key)
+      @data.key?(key.to_s)
+    end
+
+    def to_h
+      @data.transform_values { |value| Util.plain(value) }
+    end
+    alias to_hash to_h
+
+    def inspect
+      "#<#{self.class}>"
+    end
+    alias to_s inspect
+  end
+end

data/lib/raims/api_response.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Raims
+  class ApiResponse
+    attr_reader :status_code, :headers
+
+    def initialize(status_code, headers = {})
+      @status_code = status_code
+      @headers = Util.deep_freeze(headers.each_with_object({}) { |(key, value), result| result[key.to_s.downcase] = value.to_s.dup })
+      freeze
+    end
+
+    def request_id
+      headers['request-id'] || headers['x-request-id']
+    end
+
+    def retry_after
+      headers['retry-after']
+    end
+
+    def idempotency_replayed?
+      headers.fetch('idempotency-replayed', '').casecmp?('true')
+    end
+
+    def inspect
+      "#<#{self.class} status_code=#{status_code}>"
+    end
+    alias to_s inspect
+  end
+
+  class HttpResponse
+    attr_reader :status, :headers, :body
+
+    def initialize(status:, headers:, body:)
+      @status = status
+      @headers = headers
+      @body = body
+    end
+
+    def inspect
+      "#<#{self.class} status=#{status}>"
+    end
+    alias to_s inspect
+  end
+end

data/lib/raims/enum_values.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+# Generated by scripts/generate.py. Do not edit.
+
+module Raims
+  module EnumValues
+    ACCOUNT_CONTEXT_AMOUNT_UNIT_CENTS = 'cents'
+    ACCOUNT_CONTEXT_BUSINESS_TIMEZONE_AMERICA_SAO_PAULO = 'America/Sao_Paulo'
+    ACCOUNT_CONTEXT_COMPANY_STATUS_ACTIVE = 'active'
+    ACCOUNT_CONTEXT_COMPANY_STATUS_LIMITED = 'limited'
+    ACCOUNT_CONTEXT_COMPANY_STATUS_PENDING = 'pending'
+    ACCOUNT_CONTEXT_CURRENCY_BRL = 'BRL'
+    ACCOUNT_CONTEXT_DATA_ENVIRONMENT_PRODUCTION = 'production'
+    ACCOUNT_CONTEXT_DATA_ENVIRONMENT_SANDBOX = 'sandbox'
+    ACCOUNT_CONTEXT_TIMESTAMP_UNIT_UNIX_SECONDS = 'unix_seconds'
+    BALANCE_FORECAST_PERIOD_LAST_15_DAYS = 'last_15_days'
+    BALANCE_FORECAST_PERIOD_LAST_30_DAYS = 'last_30_days'
+    BALANCE_FORECAST_PERIOD_LAST_7_DAYS = 'last_7_days'
+    BALANCE_FORECAST_PERIOD_TODAY = 'today'
+    CHARGE_CREATED_PAYMENT_METHOD_TYPES_ITEM_BOLETO = 2
+    CHARGE_CREATED_PAYMENT_METHOD_TYPES_ITEM_PIX = 1
+    CHARGE_LIST_ITEM_PAYMENT_METHOD_TYPES_ITEM_BOLETO = 2
+    CHARGE_LIST_ITEM_PAYMENT_METHOD_TYPES_ITEM_PIX = 1
+    CHARGE_PAYMENT_INFORMATION_BOLETO_PAYMENT_STATUS_AWAITING_PAYMENT = 'awaiting_payment'
+    CHARGE_PAYMENT_INFORMATION_BOLETO_PAYMENT_STATUS_COMPENSATED = 'compensated'
+    CHARGE_PAYMENT_INFORMATION_BOLETO_PAYMENT_STATUS_SETTLED = 'settled'
+    CHARGE_PAYMENT_INFORMATION_BOLETO_STATUS_AVAILABLE = 'available'
+    CHARGE_PAYMENT_INFORMATION_BOLETO_STATUS_FAILED = 'failed'
+    CHARGE_PAYMENT_INFORMATION_BOLETO_STATUS_NOT_GENERATED = 'not_generated'
+    CHARGE_PAYMENT_INFORMATION_BOLETO_STATUS_PENDING = 'pending'
+    CHARGE_PAYMENT_INFORMATION_PIX_STATUS_AVAILABLE = 'available'
+    CHARGE_PAYMENT_INFORMATION_PIX_STATUS_FAILED = 'failed'
+    CHARGE_PAYMENT_INFORMATION_PIX_STATUS_NOT_GENERATED = 'not_generated'
+    CHARGE_PAYMENT_INFORMATION_PIX_STATUS_PENDING = 'pending'
+    CHARGE_PAYMENT_METHOD_TYPES_ITEM_BOLETO = 2
+    CHARGE_PAYMENT_METHOD_TYPES_ITEM_PIX = 1
+    CHARGE_SCENARIO_ACTION_BOLETO_ISSUANCE = 'boleto_issuance'
+    CHARGE_SCENARIO_ACTION_CANCELLATION = 'cancellation'
+    CHARGE_SCENARIO_ACTION_PIX_ISSUANCE = 'pix_issuance'
+    CHARGE_SCENARIO_OUTCOME_COMPLETED = 'completed'
+    CHARGE_SCENARIO_OUTCOME_FAILED = 'failed'
+    CHARGE_SCENARIO_OUTCOME_PENDING = 'pending'
+    CHARGE_SCENARIO_REQUEST_ACTION_BOLETO_ISSUANCE = 'boleto_issuance'
+    CHARGE_SCENARIO_REQUEST_ACTION_CANCELLATION = 'cancellation'
+    CHARGE_SCENARIO_REQUEST_ACTION_PIX_ISSUANCE = 'pix_issuance'
+    CHARGE_SCENARIO_REQUEST_OUTCOME_FAILED = 'failed'
+    CHARGE_SCENARIO_REQUEST_OUTCOME_PENDING = 'pending'
+    CHARGE_SCENARIO_STATE_COMPLETED = 'completed'
+    CHARGE_SCENARIO_STATE_CONFIGURED = 'configured'
+    CHARGE_SCENARIO_STATE_FAILED = 'failed'
+    CHARGE_SCENARIO_STATE_PENDING = 'pending'
+    CHARGE_STATISTICS_PERIOD_LAST_15_DAYS = 'last_15_days'
+    CHARGE_STATISTICS_PERIOD_LAST_30_DAYS = 'last_30_days'
+    CHARGE_STATISTICS_PERIOD_LAST_7_DAYS = 'last_7_days'
+    CHARGE_STATISTICS_PERIOD_TODAY = 'today'
+    CHECKOUT_ASSET_ERROR_CODE_CHECKOUT_ASSET_INVALID_IMAGE = 'CHECKOUT_ASSET_INVALID_IMAGE'
+    CHECKOUT_ASSET_ERROR_CODE_CHECKOUT_ASSET_PROCESSING_FAILED = 'CHECKOUT_ASSET_PROCESSING_FAILED'
+    CHECKOUT_ASSET_ERROR_CODE_CHECKOUT_ASSET_UPLOAD_NOT_FOUND = 'CHECKOUT_ASSET_UPLOAD_NOT_FOUND'
+    CHECKOUT_ASSET_STATUS_ABSENT = 'absent'
+    CHECKOUT_ASSET_STATUS_FAILED = 'failed'
+    CHECKOUT_ASSET_STATUS_PENDING = 'pending'
+    CHECKOUT_ASSET_STATUS_READY = 'ready'
+    CHECKOUT_ASSET_UPLOAD_CONTENT_TYPE_IMAGE_JPEG = 'image/jpeg'
+    CHECKOUT_ASSET_UPLOAD_CONTENT_TYPE_IMAGE_PNG = 'image/png'
+    CREATE_CHARGE_REQUEST_PAYMENT_METHOD_BOLETO = 2
+    CREATE_CHARGE_REQUEST_PAYMENT_METHOD_INDEFINIDO = 0
+    CREATE_CHARGE_REQUEST_PAYMENT_METHOD_PIX = 1
+    CREATE_CHARGE_REQUEST_PAYMENT_METHOD_TYPES_ITEM_BOLETO = 2
+    CREATE_CHARGE_REQUEST_PAYMENT_METHOD_TYPES_ITEM_PIX = 1
+    CREATE_CHECKOUT_FAVICON_UPLOAD_REQUEST_CONTENT_TYPE_IMAGE_JPEG = 'image/jpeg'
+    CREATE_CHECKOUT_FAVICON_UPLOAD_REQUEST_CONTENT_TYPE_IMAGE_PNG = 'image/png'
+    CREATE_CHECKOUT_LOGO_UPLOAD_REQUEST_CONTENT_TYPE_IMAGE_JPEG = 'image/jpeg'
+    CREATE_CHECKOUT_LOGO_UPLOAD_REQUEST_CONTENT_TYPE_IMAGE_PNG = 'image/png'
+    CREATE_PAYMENT_LINK_REQUEST_PAYMENT_METHOD_TYPES_ITEM_BOLETO = 2
+    CREATE_PAYMENT_LINK_REQUEST_PAYMENT_METHOD_TYPES_ITEM_PIX = 1
+    CREATE_WEBHOOK_REQUEST_EVENTS_ITEM_CHARGE_CANCELED = 'charge.canceled'
+    CREATE_WEBHOOK_REQUEST_EVENTS_ITEM_CHARGE_CREATED = 'charge.created'
+    CREATE_WEBHOOK_REQUEST_EVENTS_ITEM_CHARGE_FAILED = 'charge.failed'
+    CREATE_WEBHOOK_REQUEST_EVENTS_ITEM_CHARGE_PAID = 'charge.paid'
+    CREATE_WEBHOOK_REQUEST_EVENTS_ITEM_REFUND_COMPLETED = 'refund.completed'
+    CREATE_WEBHOOK_REQUEST_EVENTS_ITEM_REFUND_FAILED = 'refund.failed'
+    CREATE_WEBHOOK_REQUEST_EVENTS_ITEM_REFUND_REQUESTED = 'refund.requested'
+    CUSTOMER_CREATED_TAX_ID_TYPE_CNPJ = 'cnpj'
+    CUSTOMER_CREATED_TAX_ID_TYPE_CPF = 'cpf'
+    CUSTOMER_LIST_ITEM_TAX_ID_TYPE_CNPJ = 'cnpj'
+    CUSTOMER_LIST_ITEM_TAX_ID_TYPE_CPF = 'cpf'
+    DISPUTE_INFRACTION_RESULT_AGREED = 'agreed'
+    DISPUTE_INFRACTION_RESULT_DISAGREED = 'disagreed'
+    DISPUTE_KIND_CHARGEBACK = 'chargeback'
+    DISPUTE_KIND_MED = 'med'
+    DISPUTE_LIST_ITEM_KIND_CHARGEBACK = 'chargeback'
+    DISPUTE_LIST_ITEM_KIND_MED = 'med'
+    DISPUTE_LIST_ITEM_STAGE_CANCELLED = 'cancelled'
+    DISPUTE_LIST_ITEM_STAGE_CLOSED = 'closed'
+    DISPUTE_LIST_ITEM_STAGE_FAILED = 'failed'
+    DISPUTE_LIST_ITEM_STAGE_IN_ANALYSIS = 'in_analysis'
+    DISPUTE_LIST_ITEM_STAGE_OPEN = 'open'
+    DISPUTE_LIST_ITEM_STAGE_REFUND_IN_ANALYSIS = 'refund_in_analysis'
+    DISPUTE_LIST_ITEM_STAGE_REJECTED = 'rejected'
+    DISPUTE_REFUND_RESULT_PARTIALLY_ACCEPTED = 'partially_accepted'
+    DISPUTE_REFUND_RESULT_REJECTED = 'rejected'
+    DISPUTE_REFUND_RESULT_TOTALLY_ACCEPTED = 'totally_accepted'
+    DISPUTE_STAGE_CANCELLED = 'cancelled'
+    DISPUTE_STAGE_CLOSED = 'closed'
+    DISPUTE_STAGE_FAILED = 'failed'
+    DISPUTE_STAGE_IN_ANALYSIS = 'in_analysis'
+    DISPUTE_STAGE_OPEN = 'open'
+    DISPUTE_STAGE_REFUND_IN_ANALYSIS = 'refund_in_analysis'
+    DISPUTE_STAGE_REJECTED = 'rejected'
+    PAYMENT_LINK_DETAILS_EFFECTIVE_PAYMENT_METHOD_TYPES_ITEM_BOLETO = 2
+    PAYMENT_LINK_DETAILS_EFFECTIVE_PAYMENT_METHOD_TYPES_ITEM_PIX = 1
+    PAYMENT_LINK_DETAILS_PAYMENT_METHOD_TYPES_ITEM_BOLETO = 2
+    PAYMENT_LINK_DETAILS_PAYMENT_METHOD_TYPES_ITEM_PIX = 1
+    PAYMENT_LINK_PAYMENT_METHOD_TYPES_ITEM_BOLETO = 2
+    PAYMENT_LINK_PAYMENT_METHOD_TYPES_ITEM_PIX = 1
+    PAYMENT_LINK_UNAVAILABLE_REASON_CODE_BOLETO_AWAITING_SETTLEMENT = 'BOLETO_AWAITING_SETTLEMENT'
+    PAYMENT_LINK_UNAVAILABLE_REASON_CODE_CHARGE_EXPIRED = 'CHARGE_EXPIRED'
+    PAYMENT_LINK_UNAVAILABLE_REASON_CODE_CHARGE_NOT_OPEN = 'CHARGE_NOT_OPEN'
+    PAYMENT_LINK_UNAVAILABLE_REASON_CODE_PAYMENT_LINK_PAUSED = 'PAYMENT_LINK_PAUSED'
+    PAYMENT_LINK_UNAVAILABLE_REASON_CODE_PAYMENT_METHODS_UNAVAILABLE = 'PAYMENT_METHODS_UNAVAILABLE'
+    PAYMENT_LINK_UNAVAILABLE_REASON_CODE_PIX_CANCELLATION_PENDING = 'PIX_CANCELLATION_PENDING'
+    PAYMENT_LINK_UNAVAILABLE_REASON_CODE_PIX_CANCELLED = 'PIX_CANCELLED'
+    REFUND_FAILURE_REASON_CODE_REFUND_FAILURE_REASON_UNAVAILABLE = 'REFUND_FAILURE_REASON_UNAVAILABLE'
+    REFUND_FAILURE_REASON_CODE_REFUND_NOT_SUBMITTED = 'REFUND_NOT_SUBMITTED'
+    REFUND_FAILURE_REASON_CODE_REFUND_PROCESSING_FAILED = 'REFUND_PROCESSING_FAILED'
+    REFUND_FAILURE_REASON_CODE_REFUND_PROCESSING_UNAVAILABLE = 'REFUND_PROCESSING_UNAVAILABLE'
+    REFUND_FAILURE_REASON_CODE_REFUND_REJECTED = 'REFUND_REJECTED'
+    REFUND_STATUS_ACCEPTED = 'accepted'
+    REFUND_STATUS_COMPLETED = 'completed'
+    REFUND_STATUS_FAILED = 'failed'
+    REFUND_STATUS_RESERVED = 'reserved'
+    REFUND_STATUS_UNKNOWN = 'unknown'
+    REFUND_UNAVAILABLE_REASON_CODE_PIX_REFUND_ALREADY_COMPLETED = 'PIX_REFUND_ALREADY_COMPLETED'
+    REFUND_UNAVAILABLE_REASON_CODE_PIX_REFUND_CASHIN_NOT_FOUND = 'PIX_REFUND_CASHIN_NOT_FOUND'
+    REFUND_UNAVAILABLE_REASON_CODE_PIX_REFUND_INSUFFICIENT_BALANCE = 'PIX_REFUND_INSUFFICIENT_BALANCE'
+    REFUND_UNAVAILABLE_REASON_CODE_PIX_REFUND_IN_PROGRESS = 'PIX_REFUND_IN_PROGRESS'
+    REFUND_UNAVAILABLE_REASON_CODE_PIX_REFUND_NOT_AVAILABLE = 'PIX_REFUND_NOT_AVAILABLE'
+    REFUND_UNAVAILABLE_REASON_CODE_PIX_REFUND_PROVIDER_ACCOUNT_NOT_READY = 'PIX_REFUND_PROVIDER_ACCOUNT_NOT_READY'
+    REFUND_UNAVAILABLE_REASON_CODE_PIX_REFUND_PROVIDER_UNAVAILABLE = 'PIX_REFUND_PROVIDER_UNAVAILABLE'
+    RESOLVE_CHARGE_SCENARIO_REQUEST_ACTION_BOLETO_ISSUANCE = 'boleto_issuance'
+    RESOLVE_CHARGE_SCENARIO_REQUEST_ACTION_CANCELLATION = 'cancellation'
+    RESOLVE_CHARGE_SCENARIO_REQUEST_ACTION_PIX_ISSUANCE = 'pix_issuance'
+    RESOLVE_CHARGE_SCENARIO_REQUEST_OUTCOME_COMPLETED = 'completed'
+    RESOLVE_CHARGE_SCENARIO_REQUEST_OUTCOME_FAILED = 'failed'
+    STATEMENT_REFERENCE_TYPE_AJUSTE = 4
+    STATEMENT_REFERENCE_TYPE_COBRAN_A = 1
+    STATEMENT_REFERENCE_TYPE_CONTESTA_O = 2
+    STATEMENT_REFERENCE_TYPE_MANUAL = 5
+    STATEMENT_REFERENCE_TYPE_SAQUE = 3
+    STATEMENT_REFERENCE_TYPE_SEM_REFER_NCIA = nil
+    STATEMENT_STATEMENT_TYPE_BLOQUEIO = 9
+    STATEMENT_STATEMENT_TYPE_CR_DITO_POR_AJUSTE = 7
+    STATEMENT_STATEMENT_TYPE_DEVOLU_O = 5
+    STATEMENT_STATEMENT_TYPE_DEVOLU_O_PARCIAL = 6
+    STATEMENT_STATEMENT_TYPE_D_BITO_POR_AJUSTE = 8
+    STATEMENT_STATEMENT_TYPE_LIBERA_O = 10
+    STATEMENT_STATEMENT_TYPE_RECEBIMENTO = 1
+    STATEMENT_STATEMENT_TYPE_SAQUE = 4
+    STATEMENT_STATEMENT_TYPE_TARIFA = 2
+    STATEMENT_STATEMENT_TYPE_TARIFA_DE_SERVI_O = 3
+    UPDATE_PAYMENT_LINK_REQUEST_PAYMENT_METHOD_TYPES_ITEM_BOLETO = 2
+    UPDATE_PAYMENT_LINK_REQUEST_PAYMENT_METHOD_TYPES_ITEM_PIX = 1
+    WEBHOOK_CREATED_DISABLED_REASON_CONTINUOUS_FAILURE = 'continuous_failure'
+    WEBHOOK_CREATED_DISABLED_REASON_MANUAL = 'manual'
+    WEBHOOK_DISABLED_REASON_CONTINUOUS_FAILURE = 'continuous_failure'
+    WEBHOOK_DISABLED_REASON_MANUAL = 'manual'
+    WEBHOOK_EVENT_TYPE_CODE_CHARGE_CANCELED = 'charge.canceled'
+    WEBHOOK_EVENT_TYPE_CODE_CHARGE_CREATED = 'charge.created'
+    WEBHOOK_EVENT_TYPE_CODE_CHARGE_FAILED = 'charge.failed'
+    WEBHOOK_EVENT_TYPE_CODE_CHARGE_PAID = 'charge.paid'
+    WEBHOOK_EVENT_TYPE_CODE_REFUND_COMPLETED = 'refund.completed'
+    WEBHOOK_EVENT_TYPE_CODE_REFUND_FAILED = 'refund.failed'
+    WEBHOOK_EVENT_TYPE_CODE_REFUND_REQUESTED = 'refund.requested'
+    WEBHOOK_HEALTH_STATUS_DISABLED = 'disabled'
+    WEBHOOK_HEALTH_STATUS_FAILING = 'failing'
+    WEBHOOK_HEALTH_STATUS_HEALTHY = 'healthy'
+    WEBHOOK_HEALTH_STATUS_UNKNOWN = 'unknown'
+    WITHDRAWAL_DESTINATION_KEY_TYPE_CNPJ = 'CNPJ'
+    WITHDRAWAL_DESTINATION_KEY_TYPE_EMAIL = 'EMAIL'
+    WITHDRAWAL_DESTINATION_KEY_TYPE_EVP = 'EVP'
+    WITHDRAWAL_DESTINATION_KEY_TYPE_PHONE = 'PHONE'
+    WITHDRAWAL_FAILURE_REASON_CODE_ABOVE_MAXIMUM_WITHDRAWAL = 'ABOVE_MAXIMUM_WITHDRAWAL'
+    WITHDRAWAL_FAILURE_REASON_CODE_BANK_ACCOUNT_UNAVAILABLE = 'BANK_ACCOUNT_UNAVAILABLE'
+    WITHDRAWAL_FAILURE_REASON_CODE_BANK_PROCESSING_FAILURE = 'BANK_PROCESSING_FAILURE'
+    WITHDRAWAL_FAILURE_REASON_CODE_BANK_TIMEOUT = 'BANK_TIMEOUT'
+    WITHDRAWAL_FAILURE_REASON_CODE_BANK_UNSUPPORTED = 'BANK_UNSUPPORTED'
+    WITHDRAWAL_FAILURE_REASON_CODE_BELOW_MINIMUM_WITHDRAWAL = 'BELOW_MINIMUM_WITHDRAWAL'
+    WITHDRAWAL_FAILURE_REASON_CODE_BLOCKED_BALANCE = 'BLOCKED_BALANCE'
+    WITHDRAWAL_FAILURE_REASON_CODE_DUPLICATED_REQUEST = 'DUPLICATED_REQUEST'
+    WITHDRAWAL_FAILURE_REASON_CODE_INSUFFICIENT_BALANCE = 'INSUFFICIENT_BALANCE'
+    WITHDRAWAL_FAILURE_REASON_CODE_INTERNAL_ERROR = 'INTERNAL_ERROR'
+    WITHDRAWAL_FAILURE_REASON_CODE_INVALID_ACCOUNT_TYPE = 'INVALID_ACCOUNT_TYPE'
+    WITHDRAWAL_FAILURE_REASON_CODE_INVALID_BANK_ACCOUNT = 'INVALID_BANK_ACCOUNT'
+    WITHDRAWAL_FAILURE_REASON_CODE_RISK_POLICY_REJECTED = 'RISK_POLICY_REJECTED'
+    WITHDRAWAL_FAILURE_REASON_CODE_WITHDRAWAL_FAILURE_REASON_UNAVAILABLE = 'WITHDRAWAL_FAILURE_REASON_UNAVAILABLE'
+    WITHDRAWAL_FAILURE_REASON_CODE_WITHDRAWAL_LIMIT_REACHED = 'WITHDRAWAL_LIMIT_REACHED'
+    WITHDRAWAL_FAILURE_REASON_CODE_WITHDRAWAL_TEMPORARILY_UNAVAILABLE = 'WITHDRAWAL_TEMPORARILY_UNAVAILABLE'
+    WITHDRAWAL_PIX_DESTINATION_KEY_TYPE_CNPJ = 'CNPJ'
+    WITHDRAWAL_PIX_DESTINATION_KEY_TYPE_EMAIL = 'EMAIL'
+    WITHDRAWAL_PIX_DESTINATION_KEY_TYPE_EVP = 'EVP'
+    WITHDRAWAL_PIX_DESTINATION_KEY_TYPE_PHONE = 'PHONE'
+    WITHDRAWAL_STATUS_CANCELED = 'CANCELED'
+    WITHDRAWAL_STATUS_COMPLETED = 'COMPLETED'
+    WITHDRAWAL_STATUS_FAILED = 'FAILED'
+    WITHDRAWAL_STATUS_PENDING = 'PENDING'
+    WITHDRAWAL_STATUS_PROCESSING = 'PROCESSING'
+    WITHDRAWAL_STATUS_UNKNOWN = 'UNKNOWN'
+  end
+end

data/lib/raims/errors.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Raims
+  class RaimsError < StandardError
+    attr_reader :last_response, :api_error
+
+    def initialize(message, last_response: nil, api_error: nil)
+      super(message)
+      @last_response = last_response
+      @api_error = api_error && Util.deep_freeze(api_error)
+    end
+
+    def http_status
+      last_response&.status_code
+    end
+    alias status_code http_status
+
+    def request_id
+      last_response&.request_id
+    end
+
+    def retry_after
+      last_response&.retry_after
+    end
+
+    def code
+      value = api_error && api_error['code']
+      value if value.is_a?(String)
+    end
+
+    def param
+      api_error && api_error['param']
+    end
+
+    def errors
+      api_error && api_error['errors']
+    end
+
+    def details
+      value = api_error && api_error['details']
+      value if value.is_a?(Array)
+    end
+
+    def inspect
+      "#<#{self.class} http_status=#{http_status.inspect}>"
+    end
+  end
+
+  class ApiError < RaimsError; end
+  class AuthenticationError < ApiError; end
+  class PermissionError < ApiError; end
+  class NotFoundError < ApiError; end
+  class InvalidRequestError < ApiError; end
+  class ConflictError < ApiError; end
+  class RateLimitError < ApiError; end
+  class ConnectionError < RaimsError; end
+  class UnexpectedResponseError < RaimsError; end
+  class SignatureVerificationError < RaimsError; end
+end