alchemrest 3.1.0

data/Rakefile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+Bundler::GemHelper.install_tasks
+Bundler::GemHelper.tag_prefix = "#{Bundler::GemHelper.gemspec.name}-"
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+def default_task
+  if ENV['APPRAISAL_INITIALIZED'] || ENV['CI']
+    %i(rubocop spec)
+  else
+    require 'appraisal'
+    Appraisal::Task.new
+    %i(appraisal)
+  end
+end
+
+task(:default).clear.enhance(default_task)

data/alchemrest.gemspec

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "lib/alchemrest/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "alchemrest"
+  spec.version = Alchemrest::VERSION
+  spec.authors = ["Andrew Swerlick", "James Boyer"]
+  spec.email = ["andrew.swerlick@betterment.com", "james.boyer@betterment.com"]
+
+  spec.summary = %(
+    A library to help you transform third party api's into a set of classes and models
+    designed to work nicely with your domain.
+  )
+  spec.description = %(
+    Betterment's library for building robust, reliable, performant integrations with
+    third party apis, with a focus on making APIs work with the rest of your domain layer
+    not against it.
+  )
+  spec.license = "MIT"
+  spec.homepage = "https://github.com/Betterment/alchemrest"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata["changelog_uri"] = "https://github.com/Betterment/alchemrest/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = %w(lib)
+
+  rails_constraints = [">= 7.2", "< 8.1"]
+
+  spec.add_dependency 'activerecord', rails_constraints
+  spec.add_dependency 'activesupport', rails_constraints
+  spec.add_dependency "circuitbox", "~> 2.0.0"
+  spec.add_dependency "faraday", ">= 1.10", "< 3.0"
+  spec.add_dependency "memosa", ">= 0.8.2"
+  spec.add_dependency 'money', '>= 6.0'
+  spec.add_dependency 'morpher', '>=0.4.1'
+  spec.add_dependency 'multi_json', '~> 1.0'
+  spec.add_dependency 'mustermann-contrib', '>= 1.0'
+  spec.add_dependency 'railties', rails_constraints
+  spec.add_dependency 'sentry-ruby'
+  spec.add_dependency 'sorbet-runtime', '>= 0.5.0'
+
+  spec.add_development_dependency "activemodel"
+  spec.add_development_dependency 'appraisal'
+  spec.add_development_dependency "betterlint"
+  spec.add_development_dependency 'combustion'
+  spec.add_development_dependency "factory_bot"
+  spec.add_development_dependency "moneta"
+  spec.add_development_dependency 'mutant-rspec', '~> 0.13.4'
+  spec.add_development_dependency 'pg'
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rspec_junit_formatter"
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'sorbet'
+  spec.add_development_dependency 'tapioca', '>= 0.16.6'
+  spec.add_development_dependency "timecop"
+  spec.add_development_dependency "webmock"
+end

data/coach.yml

@@ -0,0 +1,5 @@
+project_type: ruby_gem
+ruby_version: 3.2.2
+databases:
+  - type: postgresql
+    version: "15.2"

data/examples/bank_api/client.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# typed: true
+
+class BankApi::Client < Alchemrest::Client
+  configure do |config|
+    config.connection.url = 'http://bank.example.com'
+    config.service_name = "bank"
+    config.use_kill_switch(true)
+    config.use_circuit_breaker(disabled_when: -> { ENV.fetch("DISABLE_BANK_API_CIRCUIT", nil) })
+    config.connection.customize do |c|
+      c.options[:open_timeout] = 4
+      c.options[:timeout] = 10
+    end
+  end
+
+  def build_response(raw_response)
+    Response.new(raw_response)
+  end
+
+  class Response < Alchemrest::Response
+    def error_details
+      error_data = body.fetch("errors", {})
+      case error_data
+      when Hash
+        error_data.symbolize_keys
+      else
+        error_data
+      end
+    end
+  end
+end

data/examples/bank_api/data/account.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# typed: true
+
+module BankApi
+  module Data
+    class Account < Alchemrest::Data
+      schema do |s|
+        {
+          required: {
+            name: s.string,
+            status: s.enum(%w(open locked)),
+            cards: s.many_of(BankApi::Data::Card),
+          },
+          optional: {
+            nickname: s.string,
+          },
+        }
+      end
+    end
+  end
+end

data/examples/bank_api/data/ach.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module BankApi
+  module Data
+    class Ach < Alchemrest::Data
+      schema do |s|
+        {
+          required: {
+            source_type: s.enum(%w(ach)),
+            trace_number: s.from.string.where.max_length(15),
+          },
+        }
+      end
+    end
+  end
+end

data/examples/bank_api/data/business_account.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# typed: true
+
+module BankApi
+  module Data
+    class BusinessAccount < Alchemrest::Data
+      schema do |s|
+        {
+          required: {
+            name: s.string,
+            status: s.enum(%w(open locked)),
+            ein: s.string,
+            id: s.string,
+          },
+          optional: {
+            nickname: s.string,
+          },
+        }
+      end
+    end
+  end
+end

data/examples/bank_api/data/card.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# typed: true
+
+module BankApi
+  module Data
+    class Card < Alchemrest::Data
+      schema do |s|
+        {
+          required: {
+            source_type: s.enum(%w(card)),
+            card_number: s.string,
+            expiration_date: s.from.string.to(Time).using(:utc, require_offset: false),
+          },
+          optional: {
+            secondary_user: s.one_of(User),
+          },
+        }
+      end
+    end
+  end
+end

data/examples/bank_api/data/check.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# typed: true
+
+module BankApi
+  module Data
+    class Check < Alchemrest::Data
+      schema do |s|
+        {
+          required: {
+            source_type: s.enum(%w(check)),
+            check_number: s.integer,
+            check_image_back_url: s.string,
+            check_image_front_url: s.string,
+          },
+        }
+      end
+    end
+  end
+end

data/examples/bank_api/data/product.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# typed: true
+
+module BankApi
+  module Data
+    class Product < Alchemrest::Data
+      schema do |s|
+        {
+          required: {
+            name: s.string,
+            interest_rate: PositiveInterestString.new(2),
+            partner_revenue_rate: s.from.string.where.matches(/^\d+(?:\.\d{1,4})?$/).to(BigDecimal).where("less than 10") do |input|
+                                    input < 10
+                                  end,
+          },
+        }
+      end
+    end
+  end
+end

data/examples/bank_api/data/transaction.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+# typed: true
+
+module BankApi
+  module Data
+    class Transaction < Alchemrest::Data
+      schema do |s|
+        {
+          required: {
+            amount_cents: s.money(:cents),
+            status: s.enum(%w(completed pending)),
+            settled_at: s.from.string.to(Time).using(:local),
+            description: s.string,
+            account_id: s.string,
+            user_id: s.number,
+          },
+          optional: {
+            source: s.one_of(
+              check: BankApi::Data::Check,
+              card: BankApi::Data::Card,
+              ach: BankApi::Data::Ach,
+              discriminator: :source_type,
+            ),
+          },
+        }
+      end
+
+      def source_identifer
+        case (source = self.source)
+        when BankApi::Data::Check
+          source.check_number
+        when BankApi::Data::Card
+          source.card_number
+        when BankApi::Data::Ach
+          source.trace_number
+        when nil
+          nil
+        else
+          T.absurd(source)
+        end
+      end
+
+      configure_response_capture do
+        safe :account_id
+        omitted :description
+      end
+    end
+  end
+end

data/examples/bank_api/data/user.rb

@@ -0,0 +1,27 @@
+# typed: true
+# frozen_string_literal: true
+
+module BankApi
+  module Data
+    class User < Alchemrest::Data
+      schema do |s|
+        {
+          required: {
+            name: s.string,
+            status: s.enum(%w(open locked)),
+            date_of_birth: s.from.string.to(Time).using(:utc, require_offset: false),
+            account_ids: s.integer.array,
+          },
+          optional: {
+            nickname: s.string,
+          },
+        }
+      end
+
+      def age
+        # NOTE: This isn't actually correct for a variety of reasons, just an example
+        ActiveSupport::TimeZone["UTC"].now.year - date_of_birth.year
+      end
+    end
+  end
+end

data/examples/bank_api/factories.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'factory_bot'
+
+Alchemrest::FactoryBot.enable!
+
+FactoryBot.define do
+  alchemrest_factory :bank_api_user, class: 'BankApi::Data::User' do
+    name { 'Kevin' }
+    status { 'open' }
+    date_of_birth { '2021-01-01T00:00:00' }
+    account_ids { [1, 2] }
+  end
+
+  alchemrest_factory :bank_api_transaction, class: 'BankApi::Data::Transaction' do
+    sequence(:user_id)
+    amount_cents { 120_00 }
+    status { "completed" }
+    settled_at { "2023-10-10T00:00:00Z" }
+    description { "check transaction" }
+    source { association(:bank_api_check) }
+    account_id { "123456789" }
+
+    trait :from_ach do
+      source { association(:bank_api_ach) }
+    end
+
+    trait :from_check do
+      source { association(:bank_api_check) }
+    end
+
+    trait :from_card do
+      source { association(:bank_api_card) }
+    end
+  end
+
+  alchemrest_factory :bank_api_check, class: 'BankApi::Data::Check' do
+    source_type { "check" }
+    check_number { 100 }
+    check_image_back_url { "http://bank.example.com/api/v1/check_images/100/back.png" }
+    check_image_front_url { "http://bank.example.com/api/v1/check_images/100/front.png" }
+  end
+
+  alchemrest_factory :bank_api_ach, class: 'BankApi::Data::Ach' do
+    source_type { "ach" }
+    trace_number { '12354689' }
+  end
+
+  alchemrest_factory :bank_api_card, class: 'BankApi::Data::Card' do
+    source_type { 'card' }
+    card_number { '12346' }
+    expiration_date { '2023-10-10T00:00:00' }
+  end
+
+  alchemrest_factory :bank_api_product, class: 'BankApi::Data::Product' do
+    name { 'Savings Account' }
+    interest_rate { "4.00%" }
+    partner_revenue_rate { "0.0125" }
+  end
+
+  alchemrest_factory :bank_api_business_account, class: 'BankApi::Data::BusinessAccount' do
+    name { 'ACME Inc' }
+    status { 'open' }
+    ein { '123456789' }
+
+    id { SecureRandom.uuid }
+  end
+end

data/examples/bank_api/graph_visualization.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+# typed: true
+
+require "active_support/core_ext/string/indent"
+
+module BankApi
+  # A simple, toy example of how to interact with the introspection interface in alchemrest.
+  # Outputs a tree like string showing the graph of all response objects defined in our examples
+  class GraphVisualization
+    extend T::Sig
+
+    sig { returns(T::Array[Alchemrest::Data::Graph]) }
+    def graphs
+      BankApi::Data.constants.sort.map do |name|
+        BankApi::Data.const_get(name).graph
+      end
+    end
+
+    def tree_string
+      io = StringIO.new
+      graphs.each do |graph|
+        print_graph!(graph, io)
+      end
+      io.string
+    end
+
+    private
+
+    sig { params(graph: Alchemrest::Data::Graph, io: StringIO, indent: Integer).void }
+    def print_graph!(graph, io, indent: 0)
+      io.puts(T.must(graph.type.name).indent(indent))
+      graph.fields.each do |key, field|
+        output_type = field.output_type
+        io.puts("- #{key} => #{output_type ? output_type.sorbet_type : 'unknown'}".indent(indent))
+        field.constraints.each do |constraint|
+          io.puts("* #{constraint.description}".indent(indent + 2))
+        end
+      end
+      graph.sub_graphs.each do |key, sub_graph|
+        io.puts "- #{key}"
+        print_graph!(sub_graph, io, indent: 2)
+      end
+    end
+  end
+end

data/examples/bank_api/positive_interest_string.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module BankApi
+  class PositiveInterestString < Morpher::Transform
+    attr_reader :decimal_places
+
+    def initialize(decimal_places) # rubocop:disable Lint/MissingSuper
+      @decimal_places = decimal_places
+    end
+
+    def call(input)
+      return failure(error(message: "Expected a string of the form '<num>%", input:)) unless input[-1] == "%"
+
+      decimal = BigDecimal(input.chop)
+      if input.chop.split(".")[1].length != decimal_places
+        failure(error(message: "Expected #{input} to have #{decimal_places} decimal_places", input:))
+      elsif decimal.negative?
+        failure(error(message: "#{input} is less than 0%", input:))
+      else
+        success(decimal)
+      end
+    rescue ArgumentError => e
+      raise unless e.message.start_with? "invalid value for BigDecimal()"
+
+      failure(
+        error(
+          message: "Expected: #{input} to be a decimal",
+          input:,
+        ),
+      )
+    end
+  end
+end

data/examples/bank_api/requests/delete_user.rb

@@ -0,0 +1,17 @@
+# typed: true
+# frozen_string_literal: true
+
+module BankApi
+  module Requests
+    class DeleteUser < Alchemrest::Request
+      def initialize(id:)
+        @id = id
+        super()
+      end
+
+      endpoint :delete, '/api/v1/users/:id' do |url|
+        url.values = { id: @id }
+      end
+    end
+  end
+end

data/examples/bank_api/requests/get_business_account.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# typed: true
+
+module BankApi
+  module Requests
+    class GetBusinessAccount < Alchemrest::Request
+      include ActiveModel::Model
+
+      enable_response_capture
+
+      attr_accessor :token, :id
+
+      endpoint :get, '/api/business_accounts/:id' do |url|
+        url.values = { id: }
+      end
+
+      returns BankApi::Data::BusinessAccount
+
+      def headers
+        { Authorization: "Bearer #{token}" }
+      end
+    end
+  end
+end

data/examples/bank_api/requests/get_products.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+# typed: true
+
+module BankApi
+  module Requests
+    class GetProducts < Alchemrest::Request
+      returns BankApi::Data::Product[]
+      endpoint :get, '/api/v1/products'
+      enable_response_capture
+    end
+  end
+end

data/examples/bank_api/requests/get_transactions.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module BankApi
+  module Requests
+    class GetTransactions < Alchemrest::Request
+      include ActiveModel::Model
+      attr_accessor :account_id, :id, :amount
+
+      returns BankApi::Data::Transaction[]
+      endpoint :get, '/api/v1/users/:id/accounts/:account_id/transactions' do |url|
+        url.values = { id:, account_id: }
+      end
+      enable_response_capture
+
+      def response_transformer
+        super.insert_after(
+          Alchemrest::Response::Pipeline::ExtractPayload,
+          ExtractUserId.new(self),
+        )
+      end
+
+      class ExtractUserId < Alchemrest::Response::Pipeline::Transform
+        def initialize(request)
+          super()
+          @request = request
+        end
+
+        def call(payload)
+          success(payload.map { |item| item.merge("user_id" => @request.id) })
+        end
+      end
+    end
+  end
+end

data/examples/bank_api/requests/get_user.rb

@@ -0,0 +1,19 @@
+# typed: true
+# frozen_string_literal: true
+
+module BankApi
+  module Requests
+    class GetUser < Alchemrest::Request
+      def initialize(id:) # rubocop:disable Lint/MissingSuper
+        @id = id
+      end
+
+      returns BankApi::Data::User
+      endpoint :get, '/api/v1/users/:id' do |url|
+        url.values = { id: @id }
+        url.query = { includeDetails: true }
+      end
+      enable_response_capture
+    end
+  end
+end

data/examples/bank_api/requests/post_transaction.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# typed: true
+
+module BankApi
+  module Requests
+    class PostTransaction < Alchemrest::Request
+      include ActiveModel::Model
+      attr_accessor :account_id, :id, :amount
+
+      endpoint :post, '/api/v1/users/:id/accounts/:account_id/transactions' do |url|
+        url.values = { id:, account_id: }
+      end
+      enable_response_capture
+
+      def body
+        { amount: }
+      end
+    end
+  end
+end

data/examples/bank_api/requests/update_user.rb

@@ -0,0 +1,28 @@
+# typed: true
+# frozen_string_literal: true
+
+module BankApi
+  module Requests
+    class UpdateUser < Alchemrest::Request
+      def initialize(id:, name:, date_of_birth:)
+        @id = id
+        @name = name
+        @date_of_birth = date_of_birth
+        super()
+      end
+
+      endpoint :patch, '/api/v1/users/:id' do |url|
+        url.values = { id: @id }
+      end
+
+      def body
+        {
+          name: @name,
+          date_of_birth: @date_of_birth,
+        }
+      end
+
+      returns BankApi::Data::User, allow_empty_response: true
+    end
+  end
+end