feat(api): api update

.stats.yml

@@ -1,3 +1,3 @@
 configured_endpoints: 255
-openapi_spec_hash: de4578cd6e5125791bb32e1a25c9c5ac
+openapi_spec_hash: 31dbb51b621eeb3886e4e430fe825146
 config_hash: de151ebd21a0bd391662389b310a8f49

Gemfile.lock

@@ -12,6 +12,7 @@ PATH
   remote: .
   specs:
     increase (1.361.0)
+      base64
       cgi
       connection_pool
       standardwebhooks

increase.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
     ".ignore"
   ]
   s.extra_rdoc_files = ["README.md"]
+  s.add_dependency "base64"
   s.add_dependency "cgi"
   s.add_dependency "connection_pool"
   s.add_dependency "standardwebhooks"

lib/increase/internal/transport/pooled_net_requester.rb

@@ -64,6 +64,9 @@ def calibrate_socket_timeout(conn, deadline)
           # @return [Array(Net::HTTPGenericRequest, Proc)]
           def build_request(request, &blk)
             method, url, headers, body = request.fetch_values(:method, :url, :headers, :body)
+            # Streamed bodies (e.g. multipart) arrive as a factory so each attempt gets a fresh stream.
+            body = body.call if body.is_a?(Proc)
+
             req = Net::HTTPGenericRequest.new(
               method.to_s.upcase,
               !body.nil?,

lib/increase/internal/util.rb

@@ -608,34 +608,39 @@ def encode_query_params(query)
         #
         # @param body [Object]
         #
-        # @return [Array(String, Enumerable<String>)]
+        # @return [Array(String, Proc)]
         private def encode_multipart_streaming(body)
           # rubocop:disable Style/CaseEquality
           # RFC 1521 Section 7.2.1 says we should have 70 char maximum for boundary length
           boundary = SecureRandom.urlsafe_base64(46)
 
-          closing = []
-          strio = writable_enum do |y|
-            case body
-            in Hash
-              body.each do |key, val|
-                case val
-                in Array if val.all? { primitive?(_1) || Increase::Internal::Type::FileInput === _1 }
-                  val.each do |v|
-                    write_multipart_chunk(y, boundary: boundary, key: key, val: v, closing: closing)
+          # Retries and redirects resend the request, and a streamed body can only be read
+          # once, so hand back a factory that builds a fresh stream for each attempt.
+          stream = lambda do
+            closing = []
+            strio = writable_enum do |y|
+              case body
+              in Hash
+                body.each do |key, val|
+                  case val
+                  in Array if val.all? { primitive?(_1) || Increase::Internal::Type::FileInput === _1 }
+                    val.each do |v|
+                      write_multipart_chunk(y, boundary: boundary, key: key, val: v, closing: closing)
+                    end
+                  else
+                    write_multipart_chunk(y, boundary: boundary, key: key, val: val, closing: closing)
                   end
-                else
-                  write_multipart_chunk(y, boundary: boundary, key: key, val: val, closing: closing)
                 end
+              else
+                write_multipart_chunk(y, boundary: boundary, key: nil, val: body, closing: closing)
               end
-            else
-              write_multipart_chunk(y, boundary: boundary, key: nil, val: body, closing: closing)
+              y << "--#{boundary}--\r\n"
             end
-            y << "--#{boundary}--\r\n"
+
+            fused_enum(strio) { closing.each(&:call) }
           end
 
-          fused_io = fused_enum(strio) { closing.each(&:call) }
-          [boundary, fused_io]
+          [boundary, stream]
           # rubocop:enable Style/CaseEquality
         end
 

lib/increase/models/ach_transfer_create_params.rb

@@ -8,15 +8,20 @@ class ACHTransferCreateParams < Increase::Internal::Type::BaseModel
       include Increase::Internal::Type::RequestParameters
 
       # @!attribute account_id
-      #   The Increase identifier for the account that will send the transfer.
+      #   The Increase identifier for the account that will originate the transfer. For
+      #   credit transfers (transfers with a positive `amount`), this is the account that
+      #   funds will be sent from. For debit transfers (transfers with a negative
+      #   `amount`), this is the account that funds will be pulled into.
       #
       #   @return [String]
       required :account_id, String
 
       # @!attribute amount
       #   The transfer amount in USD cents. A positive amount originates a credit transfer
-      #   pushing funds to the receiving account. A negative amount originates a debit
-      #   transfer pulling funds from the receiving account.
+      #   pushing funds from Increase to the account at the other bank. A negative amount
+      #   originates a debit transfer pulling funds from the account at the other bank
+      #   into Increase. Debit transfers
+      #   [might result in a hold before funds are available](/documentation/sending-ach-debit-transfers).
       #
       #   @return [Integer]
       required :amount, Integer
@@ -33,9 +38,10 @@ class ACHTransferCreateParams < Increase::Internal::Type::BaseModel
       required :statement_descriptor, String
 
       # @!attribute account_number
-      #   The receiver's account number. For credit transfers (positive `amount`) this is
-      #   the account that funds will be sent to. For debit transfers (negative `amount`)
-      #   this is the account that funds will be pulled from.
+      #   The receiver's account number. For credit transfers (transfers with a positive
+      #   `amount`), this is the account that funds will be sent to. For debit transfers
+      #   (transfers with a negative `amount`), this is the account that funds will be
+      #   pulled from.
       #
       #   @return [String, nil]
       optional :account_number, String
@@ -58,27 +64,32 @@ class ACHTransferCreateParams < Increase::Internal::Type::BaseModel
       optional :company_descriptive_date, String
 
       # @!attribute company_discretionary_data
-      #   Custom data sent in the company batch header. This value is informational and
-      #   does not affect funds movement, settlement timing, or returns. Most ACH
-      #   transfers do not need this. Only set this if your recipient has asked for it.
+      #   Custom data sent in the company batch header, meant as metadata for the
+      #   originator. This value is informational and does not affect funds movement,
+      #   settlement timing, or returns. Most ACH transfers do not need this; we recommend
+      #   storing metadata in your own application instead.
       #
       #   @return [String, nil]
       optional :company_discretionary_data, String
 
       # @!attribute company_entry_description
-      #   A short description sent in the company batch header. Most receivers do not
-      #   surface this. Only set this if your recipient has asked for a specific value or
-      #   if Nacha mandates one for your Standard Entry Class (SEC) code and use case. For
-      #   example, Prearranged Payment and Deposit (PPD) payroll credits must use
-      #   `PAYROLL`, and reversals must use `REVERSAL`.
+      #   A short description sent in the company batch header, meant to provide the
+      #   receiver with a reason for the transfer. Many receivers do not surface this data
+      #   on the receiver's bank statement. Only set this if your recipient has asked for
+      #   a specific value or if Nacha mandates one for your Standard Entry Class (SEC)
+      #   code and use case. For example, some use cases require constants like
+      #   `ACCTVERIFY`, `PURCHASE`, `PAYROLL`, or `REVERSAL`.
       #
       #   @return [String, nil]
       optional :company_entry_description, String
 
       # @!attribute company_name
-      #   The name by which the recipient knows you, sent in the company batch header. We
-      #   recommend setting this on every transfer; if you do not, we fall back to the
-      #   `statement_descriptor`.
+      #   The name by which the recipient knows the counterparty of this transaction. If
+      #   you're processing payments on behalf of another party, use their name, not your
+      #   own, so that it's more likely the recipient understands the context of the
+      #   payment. This value is usually displayed to the recipient on their bank
+      #   statement. We recommend setting this on every transfer; if you do not, we fall
+      #   back to the `statement_descriptor`.
       #
       #   @return [String, nil]
       optional :company_name, String
@@ -106,15 +117,19 @@ class ACHTransferCreateParams < Increase::Internal::Type::BaseModel
       optional :funding, enum: -> { Increase::ACHTransferCreateParams::Funding }
 
       # @!attribute individual_id
-      #   Your internal identifier for the transfer recipient. This value is informational
-      #   and not verified by the recipient's bank. Most callers can leave this unset.
+      #   Your internal identifier for the recipient. This value is informational and
+      #   generally not verified by the recipient's bank. Most callers can leave this
+      #   unset. For the specific case of person-to-person credits with the WEB standard
+      #   entry class code, this must include the name of the payer.
       #
       #   @return [String, nil]
       optional :individual_id, String
 
       # @!attribute individual_name
-      #   The name of the transfer recipient. This value is informational and not verified
-      #   by the recipient's bank.
+      #   The name of the transfer recipient. This value is informational and generally
+      #   not verified by the recipient's bank. This value is usually displayed to the
+      #   recipient on their bank statement. We recommend setting this on every transfer;
+      #   if you do not, we fall back to the `statement_descriptor`.
       #
       #   @return [String, nil]
       optional :individual_name, String
@@ -152,12 +167,18 @@ class ACHTransferCreateParams < Increase::Internal::Type::BaseModel
                enum: -> { Increase::ACHTransferCreateParams::StandardEntryClassCode }
 
       # @!method initialize(account_id:, amount:, statement_descriptor:, account_number: nil, addenda: nil, company_descriptive_date: nil, company_discretionary_data: nil, company_entry_description: nil, company_name: nil, destination_account_holder: nil, external_account_id: nil, funding: nil, individual_id: nil, individual_name: nil, preferred_effective_date: nil, require_approval: nil, routing_number: nil, standard_entry_class_code: nil, request_options: {})
-      #   @param account_id [String] The Increase identifier for the account that will send the transfer.
+      #   @param account_id [String]
+      #     The Increase identifier for the account that will originate the transfer. For
+      #     credit transfers (transfers with a positive `amount`), this is the account that
+      #     funds will be sent from. For debit transfers (transfers with a negative
+      #     `amount`), this is the account that funds will be pulled into.
       #
       #   @param amount [Integer]
       #     The transfer amount in USD cents. A positive amount originates a credit transfer
-      #     pushing funds to the receiving account. A negative amount originates a debit
-      #     transfer pulling funds from the receiving account.
+      #     pushing funds from Increase to the account at the other bank. A negative amount
+      #     originates a debit transfer pulling funds from the account at the other bank
+      #     into Increase. Debit transfers
+      #     [might result in a hold before funds are available](/documentation/sending-ach-debit-transfers).
       #
       #   @param statement_descriptor [String]
       #     A description you choose to give the transfer. This will be saved with the
@@ -168,9 +189,10 @@ class ACHTransferCreateParams < Increase::Internal::Type::BaseModel
       #     `individual_name` and `company_name` instead of relying on this fallback.
       #
       #   @param account_number [String]
-      #     The receiver's account number. For credit transfers (positive `amount`) this is
-      #     the account that funds will be sent to. For debit transfers (negative `amount`)
-      #     this is the account that funds will be pulled from.
+      #     The receiver's account number. For credit transfers (transfers with a positive
+      #     `amount`), this is the account that funds will be sent to. For debit transfers
+      #     (transfers with a negative `amount`), this is the account that funds will be
+      #     pulled from.
       #
       #   @param addenda [Increase::Models::ACHTransferCreateParams::Addenda]
       #     Additional information passed through to the receiving bank with the transfer.
@@ -184,21 +206,26 @@ class ACHTransferCreateParams < Increase::Internal::Type::BaseModel
       #     settlement timing, or returns. Only set this if your recipient has asked for it.
       #
       #   @param company_discretionary_data [String]
-      #     Custom data sent in the company batch header. This value is informational and
-      #     does not affect funds movement, settlement timing, or returns. Most ACH
-      #     transfers do not need this. Only set this if your recipient has asked for it.
+      #     Custom data sent in the company batch header, meant as metadata for the
+      #     originator. This value is informational and does not affect funds movement,
+      #     settlement timing, or returns. Most ACH transfers do not need this; we recommend
+      #     storing metadata in your own application instead.
       #
       #   @param company_entry_description [String]
-      #     A short description sent in the company batch header. Most receivers do not
-      #     surface this. Only set this if your recipient has asked for a specific value or
-      #     if Nacha mandates one for your Standard Entry Class (SEC) code and use case. For
-      #     example, Prearranged Payment and Deposit (PPD) payroll credits must use
-      #     `PAYROLL`, and reversals must use `REVERSAL`.
+      #     A short description sent in the company batch header, meant to provide the
+      #     receiver with a reason for the transfer. Many receivers do not surface this data
+      #     on the receiver's bank statement. Only set this if your recipient has asked for
+      #     a specific value or if Nacha mandates one for your Standard Entry Class (SEC)
+      #     code and use case. For example, some use cases require constants like
+      #     `ACCTVERIFY`, `PURCHASE`, `PAYROLL`, or `REVERSAL`.
       #
       #   @param company_name [String]
-      #     The name by which the recipient knows you, sent in the company batch header. We
-      #     recommend setting this on every transfer; if you do not, we fall back to the
-      #     `statement_descriptor`.
+      #     The name by which the recipient knows the counterparty of this transaction. If
+      #     you're processing payments on behalf of another party, use their name, not your
+      #     own, so that it's more likely the recipient understands the context of the
+      #     payment. This value is usually displayed to the recipient on their bank
+      #     statement. We recommend setting this on every transfer; if you do not, we fall
+      #     back to the `statement_descriptor`.
       #
       #   @param destination_account_holder [Symbol, Increase::Models::ACHTransferCreateParams::DestinationAccountHolder]
       #     The type of entity that owns the receiver's account.
@@ -213,12 +240,16 @@ class ACHTransferCreateParams < Increase::Internal::Type::BaseModel
       #     Defaults to `checking`.
       #
       #   @param individual_id [String]
-      #     Your internal identifier for the transfer recipient. This value is informational
-      #     and not verified by the recipient's bank. Most callers can leave this unset.
+      #     Your internal identifier for the recipient. This value is informational and
+      #     generally not verified by the recipient's bank. Most callers can leave this
+      #     unset. For the specific case of person-to-person credits with the WEB standard
+      #     entry class code, this must include the name of the payer.
       #
       #   @param individual_name [String]
-      #     The name of the transfer recipient. This value is informational and not verified
-      #     by the recipient's bank.
+      #     The name of the transfer recipient. This value is informational and generally
+      #     not verified by the recipient's bank. This value is usually displayed to the
+      #     recipient on their bank statement. We recommend setting this on every transfer;
+      #     if you do not, we fall back to the `statement_descriptor`.
       #
       #   @param preferred_effective_date [Increase::Models::ACHTransferCreateParams::PreferredEffectiveDate]
       #     Configuration for how the effective date of the transfer will be set. This