lithic 0.1.0.pre.alpha.1

data/lib/lithic/models/transfer.rb

@@ -0,0 +1,396 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Models
+    class Transfer < Lithic::BaseModel
+      # @!attribute [r] token
+      #   Globally unique identifier for the transfer event.
+      #
+      #   @return [String, nil]
+      optional :token, String
+
+      # @!parse
+      #   # @return [String]
+      #   attr_writer :token
+
+      # @!attribute [r] category
+      #   Status types:
+      #
+      #     - `TRANSFER` - Internal transfer of funds between financial accounts in your
+      #       program.
+      #
+      #   @return [Symbol, Lithic::Models::Transfer::Category, nil]
+      optional :category, enum: -> { Lithic::Models::Transfer::Category }
+
+      # @!parse
+      #   # @return [Symbol, Lithic::Models::Transfer::Category]
+      #   attr_writer :category
+
+      # @!attribute [r] created
+      #   Date and time when the transfer occurred. UTC time zone.
+      #
+      #   @return [Time, nil]
+      optional :created, Time
+
+      # @!parse
+      #   # @return [Time]
+      #   attr_writer :created
+
+      # @!attribute [r] currency
+      #   3-character alphabetic ISO 4217 code for the settling currency of the
+      #     transaction.
+      #
+      #   @return [String, nil]
+      optional :currency, String
+
+      # @!parse
+      #   # @return [String]
+      #   attr_writer :currency
+
+      # @!attribute [r] descriptor
+      #   A string that provides a description of the transfer; may be useful to display
+      #     to users.
+      #
+      #   @return [String, nil]
+      optional :descriptor, String
+
+      # @!parse
+      #   # @return [String]
+      #   attr_writer :descriptor
+
+      # @!attribute [r] events
+      #   A list of all financial events that have modified this trasnfer.
+      #
+      #   @return [Array<Lithic::Models::Transfer::Event>, nil]
+      optional :events, -> { Lithic::ArrayOf[Lithic::Models::Transfer::Event] }
+
+      # @!parse
+      #   # @return [Array<Lithic::Models::Transfer::Event>]
+      #   attr_writer :events
+
+      # @!attribute [r] from_balance
+      #   The updated balance of the sending financial account.
+      #
+      #   @return [Array<Lithic::Models::Balance>, nil]
+      optional :from_balance, -> { Lithic::ArrayOf[Lithic::Models::Balance] }
+
+      # @!parse
+      #   # @return [Array<Lithic::Models::Balance>]
+      #   attr_writer :from_balance
+
+      # @!attribute [r] pending_amount
+      #   Pending amount of the transaction in the currency's smallest unit (e.g., cents),
+      #     including any acquirer fees. The value of this field will go to zero over time
+      #     once the financial transaction is settled.
+      #
+      #   @return [Integer, nil]
+      optional :pending_amount, Integer
+
+      # @!parse
+      #   # @return [Integer]
+      #   attr_writer :pending_amount
+
+      # @!attribute [r] result
+      #   APPROVED transactions were successful while DECLINED transactions were declined
+      #     by user, Lithic, or the network.
+      #
+      #   @return [Symbol, Lithic::Models::Transfer::Result, nil]
+      optional :result, enum: -> { Lithic::Models::Transfer::Result }
+
+      # @!parse
+      #   # @return [Symbol, Lithic::Models::Transfer::Result]
+      #   attr_writer :result
+
+      # @!attribute [r] settled_amount
+      #   Amount of the transaction that has been settled in the currency's smallest unit
+      #     (e.g., cents).
+      #
+      #   @return [Integer, nil]
+      optional :settled_amount, Integer
+
+      # @!parse
+      #   # @return [Integer]
+      #   attr_writer :settled_amount
+
+      # @!attribute [r] status
+      #   Status types:
+      #
+      #     - `DECLINED` - The transfer was declined.
+      #     - `EXPIRED` - The transfer was held in pending for too long and expired.
+      #     - `PENDING` - The transfer is pending release from a hold.
+      #     - `SETTLED` - The transfer is completed.
+      #     - `VOIDED` - The transfer was reversed before it settled.
+      #
+      #   @return [Symbol, Lithic::Models::Transfer::Status, nil]
+      optional :status, enum: -> { Lithic::Models::Transfer::Status }
+
+      # @!parse
+      #   # @return [Symbol, Lithic::Models::Transfer::Status]
+      #   attr_writer :status
+
+      # @!attribute [r] to_balance
+      #   The updated balance of the receiving financial account.
+      #
+      #   @return [Array<Lithic::Models::Balance>, nil]
+      optional :to_balance, -> { Lithic::ArrayOf[Lithic::Models::Balance] }
+
+      # @!parse
+      #   # @return [Array<Lithic::Models::Balance>]
+      #   attr_writer :to_balance
+
+      # @!attribute [r] updated
+      #   Date and time when the financial transaction was last updated. UTC time zone.
+      #
+      #   @return [Time, nil]
+      optional :updated, Time
+
+      # @!parse
+      #   # @return [Time]
+      #   attr_writer :updated
+
+      # @!parse
+      #   # @param token [String]
+      #   # @param category [Symbol, Lithic::Models::Transfer::Category]
+      #   # @param created [Time]
+      #   # @param currency [String]
+      #   # @param descriptor [String]
+      #   # @param events [Array<Lithic::Models::Transfer::Event>]
+      #   # @param from_balance [Array<Lithic::Models::Balance>]
+      #   # @param pending_amount [Integer]
+      #   # @param result [Symbol, Lithic::Models::Transfer::Result]
+      #   # @param settled_amount [Integer]
+      #   # @param status [Symbol, Lithic::Models::Transfer::Status]
+      #   # @param to_balance [Array<Lithic::Models::Balance>]
+      #   # @param updated [Time]
+      #   #
+      #   def initialize(
+      #     token: nil,
+      #     category: nil,
+      #     created: nil,
+      #     currency: nil,
+      #     descriptor: nil,
+      #     events: nil,
+      #     from_balance: nil,
+      #     pending_amount: nil,
+      #     result: nil,
+      #     settled_amount: nil,
+      #     status: nil,
+      #     to_balance: nil,
+      #     updated: nil,
+      #     **
+      #   )
+      #     super
+      #   end
+
+      # def initialize: (Hash | Lithic::BaseModel) -> void
+
+      # Status types:
+      #
+      #   - `TRANSFER` - Internal transfer of funds between financial accounts in your
+      #     program.
+      module Category
+        extend Lithic::Enum
+
+        TRANSFER = :TRANSFER
+
+        finalize!
+
+        # @!parse
+        #   # @return [Array<Symbol>]
+        #   def self.values; end
+      end
+
+      class Event < Lithic::BaseModel
+        # @!attribute [r] token
+        #   Globally unique identifier.
+        #
+        #   @return [String, nil]
+        optional :token, String
+
+        # @!parse
+        #   # @return [String]
+        #   attr_writer :token
+
+        # @!attribute [r] amount
+        #   Amount of the financial event that has been settled in the currency's smallest
+        #     unit (e.g., cents).
+        #
+        #   @return [Integer, nil]
+        optional :amount, Integer
+
+        # @!parse
+        #   # @return [Integer]
+        #   attr_writer :amount
+
+        # @!attribute [r] created
+        #   Date and time when the financial event occurred. UTC time zone.
+        #
+        #   @return [Time, nil]
+        optional :created, Time
+
+        # @!parse
+        #   # @return [Time]
+        #   attr_writer :created
+
+        # @!attribute [r] result
+        #   APPROVED financial events were successful while DECLINED financial events were
+        #     declined by user, Lithic, or the network.
+        #
+        #   @return [Symbol, Lithic::Models::Transfer::Event::Result, nil]
+        optional :result, enum: -> { Lithic::Models::Transfer::Event::Result }
+
+        # @!parse
+        #   # @return [Symbol, Lithic::Models::Transfer::Event::Result]
+        #   attr_writer :result
+
+        # @!attribute [r] type
+        #
+        #   @return [Symbol, Lithic::Models::Transfer::Event::Type, nil]
+        optional :type, enum: -> { Lithic::Models::Transfer::Event::Type }
+
+        # @!parse
+        #   # @return [Symbol, Lithic::Models::Transfer::Event::Type]
+        #   attr_writer :type
+
+        # @!parse
+        #   # @param token [String]
+        #   # @param amount [Integer]
+        #   # @param created [Time]
+        #   # @param result [Symbol, Lithic::Models::Transfer::Event::Result]
+        #   # @param type [Symbol, Lithic::Models::Transfer::Event::Type]
+        #   #
+        #   def initialize(token: nil, amount: nil, created: nil, result: nil, type: nil, **) = super
+
+        # def initialize: (Hash | Lithic::BaseModel) -> void
+
+        # APPROVED financial events were successful while DECLINED financial events were
+        #   declined by user, Lithic, or the network.
+        module Result
+          extend Lithic::Enum
+
+          APPROVED = :APPROVED
+          DECLINED = :DECLINED
+
+          finalize!
+
+          # @!parse
+          #   # @return [Array<Symbol>]
+          #   def self.values; end
+        end
+
+        module Type
+          extend Lithic::Enum
+
+          ACH_ORIGINATION_CANCELLED = :ACH_ORIGINATION_CANCELLED
+          ACH_ORIGINATION_INITIATED = :ACH_ORIGINATION_INITIATED
+          ACH_ORIGINATION_PROCESSED = :ACH_ORIGINATION_PROCESSED
+          ACH_ORIGINATION_RELEASED = :ACH_ORIGINATION_RELEASED
+          ACH_ORIGINATION_REVIEWED = :ACH_ORIGINATION_REVIEWED
+          ACH_ORIGINATION_SETTLED = :ACH_ORIGINATION_SETTLED
+          ACH_RECEIPT_PROCESSED = :ACH_RECEIPT_PROCESSED
+          ACH_RECEIPT_SETTLED = :ACH_RECEIPT_SETTLED
+          ACH_RETURN_INITIATED = :ACH_RETURN_INITIATED
+          ACH_RETURN_PROCESSED = :ACH_RETURN_PROCESSED
+          ACH_RETURN_SETTLED = :ACH_RETURN_SETTLED
+          AUTHORIZATION = :AUTHORIZATION
+          AUTHORIZATION_ADVICE = :AUTHORIZATION_ADVICE
+          AUTHORIZATION_EXPIRY = :AUTHORIZATION_EXPIRY
+          AUTHORIZATION_REVERSAL = :AUTHORIZATION_REVERSAL
+          BALANCE_INQUIRY = :BALANCE_INQUIRY
+          BILLING_ERROR = :BILLING_ERROR
+          BILLING_ERROR_REVERSAL = :BILLING_ERROR_REVERSAL
+          CARD_TO_CARD = :CARD_TO_CARD
+          CASH_BACK = :CASH_BACK
+          CASH_BACK_REVERSAL = :CASH_BACK_REVERSAL
+          CLEARING = :CLEARING
+          CORRECTION_CREDIT = :CORRECTION_CREDIT
+          CORRECTION_DEBIT = :CORRECTION_DEBIT
+          CREDIT_AUTHORIZATION = :CREDIT_AUTHORIZATION
+          CREDIT_AUTHORIZATION_ADVICE = :CREDIT_AUTHORIZATION_ADVICE
+          CURRENCY_CONVERSION = :CURRENCY_CONVERSION
+          CURRENCY_CONVERSION_REVERSAL = :CURRENCY_CONVERSION_REVERSAL
+          DISPUTE_WON = :DISPUTE_WON
+          EXTERNAL_ACH_CANCELED = :EXTERNAL_ACH_CANCELED
+          EXTERNAL_ACH_INITIATED = :EXTERNAL_ACH_INITIATED
+          EXTERNAL_ACH_RELEASED = :EXTERNAL_ACH_RELEASED
+          EXTERNAL_ACH_REVERSED = :EXTERNAL_ACH_REVERSED
+          EXTERNAL_ACH_SETTLED = :EXTERNAL_ACH_SETTLED
+          EXTERNAL_CHECK_CANCELED = :EXTERNAL_CHECK_CANCELED
+          EXTERNAL_CHECK_INITIATED = :EXTERNAL_CHECK_INITIATED
+          EXTERNAL_CHECK_RELEASED = :EXTERNAL_CHECK_RELEASED
+          EXTERNAL_CHECK_REVERSED = :EXTERNAL_CHECK_REVERSED
+          EXTERNAL_CHECK_SETTLED = :EXTERNAL_CHECK_SETTLED
+          EXTERNAL_TRANSFER_CANCELED = :EXTERNAL_TRANSFER_CANCELED
+          EXTERNAL_TRANSFER_INITIATED = :EXTERNAL_TRANSFER_INITIATED
+          EXTERNAL_TRANSFER_RELEASED = :EXTERNAL_TRANSFER_RELEASED
+          EXTERNAL_TRANSFER_REVERSED = :EXTERNAL_TRANSFER_REVERSED
+          EXTERNAL_TRANSFER_SETTLED = :EXTERNAL_TRANSFER_SETTLED
+          EXTERNAL_WIRE_CANCELED = :EXTERNAL_WIRE_CANCELED
+          EXTERNAL_WIRE_INITIATED = :EXTERNAL_WIRE_INITIATED
+          EXTERNAL_WIRE_RELEASED = :EXTERNAL_WIRE_RELEASED
+          EXTERNAL_WIRE_REVERSED = :EXTERNAL_WIRE_REVERSED
+          EXTERNAL_WIRE_SETTLED = :EXTERNAL_WIRE_SETTLED
+          FINANCIAL_AUTHORIZATION = :FINANCIAL_AUTHORIZATION
+          FINANCIAL_CREDIT_AUTHORIZATION = :FINANCIAL_CREDIT_AUTHORIZATION
+          INTEREST = :INTEREST
+          INTEREST_REVERSAL = :INTEREST_REVERSAL
+          INTERNAL_ADJUSTMENT = :INTERNAL_ADJUSTMENT
+          LATE_PAYMENT = :LATE_PAYMENT
+          LATE_PAYMENT_REVERSAL = :LATE_PAYMENT_REVERSAL
+          PROVISIONAL_CREDIT = :PROVISIONAL_CREDIT
+          PROVISIONAL_CREDIT_REVERSAL = :PROVISIONAL_CREDIT_REVERSAL
+          RETURN = :RETURN
+          RETURN_REVERSAL = :RETURN_REVERSAL
+          TRANSFER = :TRANSFER
+          TRANSFER_INSUFFICIENT_FUNDS = :TRANSFER_INSUFFICIENT_FUNDS
+          RETURNED_PAYMENT = :RETURNED_PAYMENT
+          RETURNED_PAYMENT_REVERSAL = :RETURNED_PAYMENT_REVERSAL
+
+          finalize!
+
+          # @!parse
+          #   # @return [Array<Symbol>]
+          #   def self.values; end
+        end
+      end
+
+      # APPROVED transactions were successful while DECLINED transactions were declined
+      #   by user, Lithic, or the network.
+      module Result
+        extend Lithic::Enum
+
+        APPROVED = :APPROVED
+        DECLINED = :DECLINED
+
+        finalize!
+
+        # @!parse
+        #   # @return [Array<Symbol>]
+        #   def self.values; end
+      end
+
+      # Status types:
+      #
+      #   - `DECLINED` - The transfer was declined.
+      #   - `EXPIRED` - The transfer was held in pending for too long and expired.
+      #   - `PENDING` - The transfer is pending release from a hold.
+      #   - `SETTLED` - The transfer is completed.
+      #   - `VOIDED` - The transfer was reversed before it settled.
+      module Status
+        extend Lithic::Enum
+
+        DECLINED = :DECLINED
+        EXPIRED = :EXPIRED
+        PENDING = :PENDING
+        SETTLED = :SETTLED
+        VOIDED = :VOIDED
+
+        finalize!
+
+        # @!parse
+        #   # @return [Array<Symbol>]
+        #   def self.values; end
+      end
+    end
+  end
+end

data/lib/lithic/models/transfer_create_params.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Models
+    class TransferCreateParams < Lithic::BaseModel
+      # @!parse
+      #   extend Lithic::RequestParameters::Converter
+      include Lithic::RequestParameters
+
+      # @!attribute amount
+      #   Amount to be transferred in the currency’s smallest unit (e.g., cents for USD).
+      #     This should always be a positive value.
+      #
+      #   @return [Integer]
+      required :amount, Integer
+
+      # @!attribute from
+      #   Globally unique identifier for the financial account or card that will send the
+      #     funds. Accepted type dependent on the program's use case.
+      #
+      #   @return [String]
+      required :from, String
+
+      # @!attribute to
+      #   Globally unique identifier for the financial account or card that will receive
+      #     the funds. Accepted type dependent on the program's use case.
+      #
+      #   @return [String]
+      required :to, String
+
+      # @!attribute [r] token
+      #   Customer-provided token that will serve as an idempotency token. This token will
+      #     become the transaction token.
+      #
+      #   @return [String, nil]
+      optional :token, String
+
+      # @!parse
+      #   # @return [String]
+      #   attr_writer :token
+
+      # @!attribute [r] memo
+      #   Optional descriptor for the transfer.
+      #
+      #   @return [String, nil]
+      optional :memo, String
+
+      # @!parse
+      #   # @return [String]
+      #   attr_writer :memo
+
+      # @!parse
+      #   # @param amount [Integer]
+      #   # @param from [String]
+      #   # @param to [String]
+      #   # @param token [String]
+      #   # @param memo [String]
+      #   # @param request_options [Lithic::RequestOptions, Hash{Symbol=>Object}]
+      #   #
+      #   def initialize(amount:, from:, to:, token: nil, memo: nil, request_options: {}, **) = super
+
+      # def initialize: (Hash | Lithic::BaseModel) -> void
+    end
+  end
+end

data/lib/lithic/models/verification_method.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Models
+    module VerificationMethod
+      extend Lithic::Enum
+
+      MANUAL = :MANUAL
+      MICRO_DEPOSIT = :MICRO_DEPOSIT
+      PLAID = :PLAID
+      PRENOTE = :PRENOTE
+      EXTERNALLY_VERIFIED = :EXTERNALLY_VERIFIED
+
+      finalize!
+
+      # @!parse
+      #   # @return [Array<Symbol>]
+      #   def self.values; end
+    end
+  end
+end

data/lib/lithic/pooled_net_requester.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Lithic
+  # @api private
+  class PooledNetRequester
+    # from the golang stdlib
+    #   https://github.com/golang/go/blob/c8eced8580028328fde7c03cbfcb720ce15b2358/src/net/http/transport.go#L49
+    KEEP_ALIVE_TIMEOUT = 30
+
+    class << self
+      # @api private
+      #
+      # @param url [URI::Generic]
+      #
+      # @return [Net::HTTP]
+      def connect(url)
+        port =
+          case [url.port, url.scheme]
+          in [Integer, _]
+            url.port
+          in [nil, "http" | "ws"]
+            Net::HTTP.http_default_port
+          in [nil, "https" | "wss"]
+            Net::HTTP.https_default_port
+          end
+
+        Net::HTTP.new(url.host, port).tap do
+          _1.use_ssl = %w[https wss].include?(url.scheme)
+          _1.max_retries = 0
+        end
+      end
+
+      # @api private
+      #
+      # @param conn [Net::HTTP]
+      # @param deadline [Float]
+      def calibrate_socket_timeout(conn, deadline)
+        timeout = deadline - Lithic::Util.monotonic_secs
+        conn.open_timeout = conn.read_timeout = conn.write_timeout = conn.continue_timeout = timeout
+      end
+
+      # @api private
+      #
+      # @param request [Hash{Symbol=>Object}] .
+      #
+      #   @option request [Symbol] :method
+      #
+      #   @option request [URI::Generic] :url
+      #
+      #   @option request [Hash{String=>String}] :headers
+      #
+      # @param blk [Proc]
+      #
+      # @yieldparam [String]
+      # @return [Net::HTTPGenericRequest]
+      def build_request(request, &)
+        method, url, headers, body = request.fetch_values(:method, :url, :headers, :body)
+        req = Net::HTTPGenericRequest.new(
+          method.to_s.upcase,
+          !body.nil?,
+          method != :head,
+          url.to_s
+        )
+
+        headers.each { req[_1] = _2 }
+
+        case body
+        in nil
+          nil
+        in String
+          req["content-length"] ||= body.bytesize.to_s unless req["transfer-encoding"]
+          req.body_stream = Lithic::Util::ReadIOAdapter.new(body, &)
+        in StringIO
+          req["content-length"] ||= body.size.to_s unless req["transfer-encoding"]
+          req.body_stream = Lithic::Util::ReadIOAdapter.new(body, &)
+        in IO | Enumerator
+          req["transfer-encoding"] ||= "chunked" unless req["content-length"]
+          req.body_stream = Lithic::Util::ReadIOAdapter.new(body, &)
+        end
+
+        req
+      end
+    end
+
+    # @api private
+    #
+    # @param url [URI::Generic]
+    # @param deadline [Float]
+    # @param blk [Proc]
+    #
+    # @raise [Timeout::Error]
+    # @yieldparam [Net::HTTP]
+    private def with_pool(url, deadline:, &blk)
+      origin = Lithic::Util.uri_origin(url)
+      timeout = deadline - Lithic::Util.monotonic_secs
+      pool =
+        @mutex.synchronize do
+          @pools[origin] ||= ConnectionPool.new(size: @size) do
+            self.class.connect(url)
+          end
+        end
+
+      pool.with(timeout: timeout, &blk)
+    end
+
+    # @api private
+    #
+    # @param request [Hash{Symbol=>Object}] .
+    #
+    #   @option request [Symbol] :method
+    #
+    #   @option request [URI::Generic] :url
+    #
+    #   @option request [Hash{String=>String}] :headers
+    #
+    #   @option request [Object] :body
+    #
+    #   @option request [Float] :deadline
+    #
+    # @return [Array(Integer, Net::HTTPResponse, Enumerable)]
+    def execute(request)
+      url, deadline = request.fetch_values(:url, :deadline)
+
+      eof = false
+      finished = false
+      enum = Enumerator.new do |y|
+        with_pool(url, deadline: deadline) do |conn|
+          next if finished
+
+          req = self.class.build_request(request) do
+            self.class.calibrate_socket_timeout(conn, deadline)
+          end
+
+          self.class.calibrate_socket_timeout(conn, deadline)
+          unless conn.started?
+            conn.keep_alive_timeout = self.class::KEEP_ALIVE_TIMEOUT
+            conn.start
+          end
+
+          self.class.calibrate_socket_timeout(conn, deadline)
+          conn.request(req) do |rsp|
+            y << [conn, req, rsp]
+            break if finished
+
+            rsp.read_body do |bytes|
+              y << bytes
+              break if finished
+
+              self.class.calibrate_socket_timeout(conn, deadline)
+            end
+            eof = true
+          end
+        end
+      rescue Timeout::Error
+        raise Lithic::APITimeoutError
+      end
+
+      conn, _, response = enum.next
+      body = Lithic::Util.fused_enum(enum, external: true) do
+        finished = true
+        tap do
+          enum.next
+        rescue StopIteration
+          nil
+        end
+        conn.finish if !eof && conn&.started?
+      end
+      [Integer(response.code), response, (response.body = body)]
+    end
+
+    # @api private
+    #
+    # @param size [Integer]
+    def initialize(size: Etc.nprocessors)
+      @mutex = Mutex.new
+      @size = size
+      @pools = {}
+    end
+  end
+end