straddle 0.3.0 → 0.5.0

data/lib/straddle/resources/payouts.rb

@@ -2,6 +2,10 @@
 
 module Straddle
   module Resources
+    # Payouts represent transfers from Straddle to customer bank accounts. Create
+    # payouts to handle disbursements, process refunds, or manage marketplace
+    # settlements. Use payouts to send money quickly and securely with the most
+    # cost-effective rail automatically selected.
     class Payouts
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::PayoutCreateParams} for more details.
@@ -14,7 +18,7 @@ module Straddle
       #
       # @param currency [String] Body param: The currency of the payout. Only USD is supported.
       #
-      # @param description [String] Body param: An arbitrary description for the payout.
+      # @param description [String, nil] Body param: An arbitrary description for the payout.
       #
       # @param device [Straddle::Models::DeviceInfoV1] Body param: Information about the device used when the customer authorized the p
       #
@@ -24,7 +28,7 @@ module Straddle
       #
       # @param payment_date [Date] Body param: The desired date on which the payout should be occur. For payouts, t
       #
-      # @param config [Straddle::Models::PayoutCreateParams::Config] Body param:
+      # @param config [Straddle::Models::PayoutCreateParams::Config] Body param
       #
       # @param metadata [Hash{Symbol=>String}, nil] Body param: Up to 20 additional user-defined key-value pairs. Useful for storing
       #
@@ -68,11 +72,11 @@ module Straddle
       #
       # @overload update(id, amount:, description:, payment_date:, metadata: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String] Path param:
+      # @param id [String] Path param
       #
       # @param amount [Integer] Body param: The amount of the payout in cents.
       #
-      # @param description [String] Body param: An arbitrary description for the payout.
+      # @param description [String, nil] Body param: An arbitrary description for the payout.
       #
       # @param payment_date [Date] Body param: The desired date on which the payment should be occur. For payouts,
       #
@@ -118,7 +122,7 @@ module Straddle
       #
       # @overload cancel(id, reason:, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String] Path param:
+      # @param id [String] Path param
       #
       # @param reason [String] Body param: Details about why the payout status was updated.
       #
@@ -195,7 +199,7 @@ module Straddle
       #
       # @overload hold(id, reason:, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String] Path param:
+      # @param id [String] Path param
       #
       # @param reason [String] Body param: Details about why the payout status was updated.
       #
@@ -239,7 +243,7 @@ module Straddle
       #
       # @overload release(id, reason:, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String] Path param:
+      # @param id [String] Path param
       #
       # @param reason [String] Body param: Details about why the payout status was updated.
       #
@@ -307,6 +311,55 @@ module Straddle
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Straddle::Models::PayoutUploadAuthorizationDocumentParams} for more details.
+      #
+      # Uploads a document as proof of authorization for a payout. Uploading again adds
+      # another entry to documents rather than replacing the previous one.
+      #
+      # @overload upload_authorization_document(id, file:, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      #
+      # @param id [String] Path param
+      #
+      # @param file [Pathname, StringIO, IO, String, Straddle::FilePart] Body param: The document file to upload as proof of authorization for this payou
+      #
+      # @param correlation_id [String] Header param: Optional client generated identifier to trace and debug a series o
+      #
+      # @param idempotency_key [String] Header param: Optional client generated value to use for idempotent requests.
+      #
+      # @param request_id [String] Header param: Optional client generated identifier to trace and debug a request.
+      #
+      # @param straddle_account_id [String] Header param: For use by platforms to specify an account id and set scope of a r
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::PayoutV1]
+      #
+      # @see Straddle::Models::PayoutUploadAuthorizationDocumentParams
+      def upload_authorization_document(id, params)
+        parsed, options = Straddle::PayoutUploadAuthorizationDocumentParams.dump_request(params)
+        header_params =
+          {
+            correlation_id: "correlation-id",
+            idempotency_key: "idempotency-key",
+            request_id: "request-id",
+            straddle_account_id: "straddle-account-id"
+          }
+        @client.request(
+          method: :post,
+          path: ["v1/payouts/%1$s/authorization", id],
+          headers: {
+            "content-type" => "multipart/form-data",
+            **parsed.slice(*header_params.keys)
+          }.transform_keys(
+            header_params
+          ),
+          body: parsed.except(*header_params.keys),
+          model: Straddle::PayoutV1,
+          options: options
+        )
+      end
+
       # @api private
       #
       # @param client [Straddle::Client]

data/lib/straddle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Straddle
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/straddle.rb

@@ -3,6 +3,7 @@
 # Standard libraries.
 # rubocop:disable Lint/RedundantRequireStatement
 require "English"
+require "base64"
 require "cgi"
 require "date"
 require "erb"
@@ -155,6 +156,7 @@ require_relative "straddle/models/payout_release_params"
 require_relative "straddle/models/payout_unmask_params"
 require_relative "straddle/models/payout_unmask_response"
 require_relative "straddle/models/payout_update_params"
+require_relative "straddle/models/payout_upload_authorization_document_params"
 require_relative "straddle/models/payout_v1"
 require_relative "straddle/models/report_create_total_customers_by_status_params"
 require_relative "straddle/models/report_create_total_customers_by_status_response"

data/manifest.yaml

@@ -1,5 +1,6 @@
 dependencies:
   - English
+  - base64
   - cgi
   - date
   - erb

data/rbi/straddle/client.rbi

@@ -27,24 +27,58 @@ module Straddle
     sig { returns(Straddle::Resources::Embed) }
     attr_reader :embed
 
+    # Bridge provides a comprehensive suite of tools for connecting customer bank
+    # accounts. Use it to generate secure widget sessions for instant account
+    # verification, accept tokens from major providers like Plaid and Finicity, or
+    # verify accounts directly via our API. Bridge handles all sensitive banking
+    # credentials and ensures secure, compliant connections with support for 90% of US
+    # bank accounts.
     sig { returns(Straddle::Resources::Bridge) }
     attr_reader :bridge
 
+    # Customers represent the end users who send or receive payments through your
+    # integration. Each customer undergoes automatic identity verification and fraud
+    # screening upon creation. Use customers to track payment history, manage bank
+    # account connections, and maintain a secure record of all transactions associated
+    # with a user. Customers can be either individuals or businesses with appropriate
+    # compliance checks for each type.
     sig { returns(Straddle::Resources::Customers) }
     attr_reader :customers
 
+    # Paykeys are secure tokens that link verified customer identities to their bank
+    # accounts. Each Paykey includes built-in balance checking, fraud detection
+    # through LSTM machine learning models, and can be reused for subscriptions and
+    # recurring payments without storing sensitive data. Paykeys eliminate fraud by
+    # ensuring the person initiating payment owns the funding account.
     sig { returns(Straddle::Resources::Paykeys) }
     attr_reader :paykeys
 
+    # Charges represent attempts to debit money from a customer's bank account using a
+    # Paykey. Each charge includes automatic balance verification, real-time fraud
+    # screening, and multi-rail optimization and detailed status tracking throughout
+    # the payment lifecycle. Use charges to accept bank payments with confidence
+    # knowing every transaction is protected.
     sig { returns(Straddle::Resources::Charges) }
     attr_reader :charges
 
+    # Funding events represent all money movement between Straddle and an Account's
+    # external bank accounts. They are automatically generated when charges settle or
+    # payouts are initiated. Each event provides detailed tracking of settlement
+    # status, fee breakdowns, and reconciliation data across both incoming and
+    # outgoing transfers. Use funding events to monitor your platform's entire money
+    # movement lifecycle.
     sig { returns(Straddle::Resources::FundingEvents) }
     attr_reader :funding_events
 
+    # Payments provide endpoints to filter both Charges and Payouts with multiple
+    # different parameters.
     sig { returns(Straddle::Resources::Payments) }
     attr_reader :payments
 
+    # Payouts represent transfers from Straddle to customer bank accounts. Create
+    # payouts to handle disbursements, process refunds, or manage marketplace
+    # settlements. Use payouts to send money quickly and securely with the most
+    # cost-effective rail automatically selected.
     sig { returns(Straddle::Resources::Payouts) }
     attr_reader :payouts
 

data/rbi/straddle/internal/util.rbi

@@ -148,12 +148,20 @@ module Straddle
         end
       end
 
+      # https://www.rfc-editor.org/rfc/rfc3986.html#section-3.3
+      RFC_3986_NOT_PCHARS = T.let(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/, Regexp)
+
       class << self
         # @api private
         sig { params(uri: URI::Generic).returns(String) }
         def uri_origin(uri)
         end
 
+        # @api private
+        sig { params(path: T.any(String, Integer)).returns(String) }
+        def encode_path(path)
+        end
+
         # @api private
         sig { params(path: T.any(String, T::Array[String])).returns(String) }
         def interpolate_path(path)
@@ -296,11 +304,31 @@ module Straddle
       end
 
       JSON_CONTENT =
-        T.let(%r{^application/(?:vnd(?:\.[^.]+)*\+)?json(?!l)}, Regexp)
+        T.let(%r{^application/(?:[a-zA-Z0-9.-]+\+)?json(?!l)}, Regexp)
       JSONL_CONTENT =
         T.let(%r{^application/(:?x-(?:n|l)djson)|(:?(?:x-)?jsonl)}, Regexp)
 
       class << self
+        # @api private
+        sig do
+          params(query: Straddle::Internal::AnyHash).returns(
+            Straddle::Internal::AnyHash
+          )
+        end
+        def encode_query_params(query)
+        end
+
+        # @api private
+        sig do
+          params(
+            collection: Straddle::Internal::AnyHash,
+            key: String,
+            element: T.anything
+          ).void
+        end
+        private def write_query_param_element!(collection, key, element)
+        end
+
         # @api private
         sig do
           params(

data/rbi/straddle/models/bridge/link_create_paykey_response.rbi

@@ -549,6 +549,11 @@ module Straddle
                 :review,
                 Straddle::Models::Bridge::LinkCreatePaykeyResponse::Data::Status::TaggedSymbol
               )
+            BLOCKED =
+              T.let(
+                :blocked,
+                Straddle::Models::Bridge::LinkCreatePaykeyResponse::Data::Status::TaggedSymbol
+              )
 
             sig do
               override.returns(
@@ -932,6 +937,41 @@ module Straddle
                   :payout_refused,
                   Straddle::Models::Bridge::LinkCreatePaykeyResponse::Data::StatusDetails::Reason::TaggedSymbol
                 )
+              CANCEL_REQUEST =
+                T.let(
+                  :cancel_request,
+                  Straddle::Models::Bridge::LinkCreatePaykeyResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              FAILED_VERIFICATION =
+                T.let(
+                  :failed_verification,
+                  Straddle::Models::Bridge::LinkCreatePaykeyResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              REQUIRE_REVIEW =
+                T.let(
+                  :require_review,
+                  Straddle::Models::Bridge::LinkCreatePaykeyResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              BLOCKED_BY_SYSTEM =
+                T.let(
+                  :blocked_by_system,
+                  Straddle::Models::Bridge::LinkCreatePaykeyResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              WATCHTOWER_REVIEW =
+                T.let(
+                  :watchtower_review,
+                  Straddle::Models::Bridge::LinkCreatePaykeyResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              VALIDATING =
+                T.let(
+                  :validating,
+                  Straddle::Models::Bridge::LinkCreatePaykeyResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              AUTO_HOLD =
+                T.let(
+                  :auto_hold,
+                  Straddle::Models::Bridge::LinkCreatePaykeyResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
 
               sig do
                 override.returns(

data/rbi/straddle/models/bridge/link_create_tan_response.rbi

@@ -545,6 +545,11 @@ module Straddle
                 :review,
                 Straddle::Models::Bridge::LinkCreateTanResponse::Data::Status::TaggedSymbol
               )
+            BLOCKED =
+              T.let(
+                :blocked,
+                Straddle::Models::Bridge::LinkCreateTanResponse::Data::Status::TaggedSymbol
+              )
 
             sig do
               override.returns(
@@ -928,6 +933,41 @@ module Straddle
                   :payout_refused,
                   Straddle::Models::Bridge::LinkCreateTanResponse::Data::StatusDetails::Reason::TaggedSymbol
                 )
+              CANCEL_REQUEST =
+                T.let(
+                  :cancel_request,
+                  Straddle::Models::Bridge::LinkCreateTanResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              FAILED_VERIFICATION =
+                T.let(
+                  :failed_verification,
+                  Straddle::Models::Bridge::LinkCreateTanResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              REQUIRE_REVIEW =
+                T.let(
+                  :require_review,
+                  Straddle::Models::Bridge::LinkCreateTanResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              BLOCKED_BY_SYSTEM =
+                T.let(
+                  :blocked_by_system,
+                  Straddle::Models::Bridge::LinkCreateTanResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              WATCHTOWER_REVIEW =
+                T.let(
+                  :watchtower_review,
+                  Straddle::Models::Bridge::LinkCreateTanResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              VALIDATING =
+                T.let(
+                  :validating,
+                  Straddle::Models::Bridge::LinkCreateTanResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
+              AUTO_HOLD =
+                T.let(
+                  :auto_hold,
+                  Straddle::Models::Bridge::LinkCreateTanResponse::Data::StatusDetails::Reason::TaggedSymbol
+                )
 
               sig do
                 override.returns(

data/rbi/straddle/models/charge_cancel_params.rbi

@@ -11,6 +11,9 @@ module Straddle
           T.any(Straddle::ChargeCancelParams, Straddle::Internal::AnyHash)
         end
 
+      sig { returns(String) }
+      attr_accessor :id
+
       # Details about why the charge status was updated.
       sig { returns(T.nilable(String)) }
       attr_accessor :reason
@@ -41,6 +44,7 @@ module Straddle
 
       sig do
         params(
+          id: String,
           reason: T.nilable(String),
           correlation_id: String,
           idempotency_key: String,
@@ -50,6 +54,7 @@ module Straddle
         ).returns(T.attached_class)
       end
       def self.new(
+        id:,
         # Details about why the charge status was updated.
         reason: nil,
         correlation_id: nil,
@@ -63,6 +68,7 @@ module Straddle
       sig do
         override.returns(
           {
+            id: String,
             reason: T.nilable(String),
             correlation_id: String,
             idempotency_key: String,

data/rbi/straddle/models/charge_create_params.rbi

@@ -33,7 +33,7 @@ module Straddle
       attr_accessor :currency
 
       # An arbitrary description for the charge.
-      sig { returns(String) }
+      sig { returns(T.nilable(String)) }
       attr_accessor :description
 
       sig { returns(Straddle::DeviceInfoV1) }
@@ -91,7 +91,7 @@ module Straddle
           config: Straddle::ChargeCreateParams::Config::OrHash,
           consent_type: Straddle::ChargeCreateParams::ConsentType::OrSymbol,
           currency: String,
-          description: String,
+          description: T.nilable(String),
           device: Straddle::DeviceInfoV1::OrHash,
           external_id: String,
           paykey: String,
@@ -144,7 +144,7 @@ module Straddle
             config: Straddle::ChargeCreateParams::Config,
             consent_type: Straddle::ChargeCreateParams::ConsentType::OrSymbol,
             currency: String,
-            description: String,
+            description: T.nilable(String),
             device: Straddle::DeviceInfoV1,
             external_id: String,
             paykey: String,
@@ -176,6 +176,14 @@ module Straddle
         end
         attr_accessor :balance_check
 
+        # Defines whether to automatically place this charge on hold after being created.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_accessor :auto_hold
+
+        # The reason the charge is being automatically held on creation.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :auto_hold_message
+
         # Payment will simulate processing if not Standard.
         sig do
           returns(
@@ -198,6 +206,8 @@ module Straddle
           params(
             balance_check:
               Straddle::ChargeCreateParams::Config::BalanceCheck::OrSymbol,
+            auto_hold: T.nilable(T::Boolean),
+            auto_hold_message: T.nilable(String),
             sandbox_outcome:
               Straddle::ChargeCreateParams::Config::SandboxOutcome::OrSymbol
           ).returns(T.attached_class)
@@ -205,6 +215,10 @@ module Straddle
         def self.new(
           # Defines whether to check the customer's balance before processing the charge.
           balance_check:,
+          # Defines whether to automatically place this charge on hold after being created.
+          auto_hold: nil,
+          # The reason the charge is being automatically held on creation.
+          auto_hold_message: nil,
           # Payment will simulate processing if not Standard.
           sandbox_outcome: nil
         )
@@ -215,6 +229,8 @@ module Straddle
             {
               balance_check:
                 Straddle::ChargeCreateParams::Config::BalanceCheck::OrSymbol,
+              auto_hold: T.nilable(T::Boolean),
+              auto_hold_message: T.nilable(String),
               sandbox_outcome:
                 Straddle::ChargeCreateParams::Config::SandboxOutcome::OrSymbol
             }
@@ -328,6 +344,16 @@ module Straddle
               :reversed_closed_bank_account,
               Straddle::ChargeCreateParams::Config::SandboxOutcome::TaggedSymbol
             )
+          FAILED_NOT_AUTHORIZED =
+            T.let(
+              :failed_not_authorized,
+              Straddle::ChargeCreateParams::Config::SandboxOutcome::TaggedSymbol
+            )
+          REVERSED_NOT_AUTHORIZED =
+            T.let(
+              :reversed_not_authorized,
+              Straddle::ChargeCreateParams::Config::SandboxOutcome::TaggedSymbol
+            )
 
           sig do
             override.returns(

data/rbi/straddle/models/charge_get_params.rbi

@@ -11,6 +11,9 @@ module Straddle
           T.any(Straddle::ChargeGetParams, Straddle::Internal::AnyHash)
         end
 
+      sig { returns(String) }
+      attr_accessor :id
+
       sig { returns(T.nilable(String)) }
       attr_reader :correlation_id
 
@@ -31,6 +34,7 @@ module Straddle
 
       sig do
         params(
+          id: String,
           correlation_id: String,
           request_id: String,
           straddle_account_id: String,
@@ -38,6 +42,7 @@ module Straddle
         ).returns(T.attached_class)
       end
       def self.new(
+        id:,
         correlation_id: nil,
         request_id: nil,
         straddle_account_id: nil,
@@ -48,6 +53,7 @@ module Straddle
       sig do
         override.returns(
           {
+            id: String,
             correlation_id: String,
             request_id: String,
             straddle_account_id: String,

data/rbi/straddle/models/charge_hold_params.rbi

@@ -11,6 +11,9 @@ module Straddle
           T.any(Straddle::ChargeHoldParams, Straddle::Internal::AnyHash)
         end
 
+      sig { returns(String) }
+      attr_accessor :id
+
       # Details about why the charge status was updated.
       sig { returns(T.nilable(String)) }
       attr_accessor :reason
@@ -41,6 +44,7 @@ module Straddle
 
       sig do
         params(
+          id: String,
           reason: T.nilable(String),
           correlation_id: String,
           idempotency_key: String,
@@ -50,6 +54,7 @@ module Straddle
         ).returns(T.attached_class)
       end
       def self.new(
+        id:,
         # Details about why the charge status was updated.
         reason: nil,
         correlation_id: nil,
@@ -63,6 +68,7 @@ module Straddle
       sig do
         override.returns(
           {
+            id: String,
             reason: T.nilable(String),
             correlation_id: String,
             idempotency_key: String,

data/rbi/straddle/models/charge_release_params.rbi

@@ -11,6 +11,9 @@ module Straddle
           T.any(Straddle::ChargeReleaseParams, Straddle::Internal::AnyHash)
         end
 
+      sig { returns(String) }
+      attr_accessor :id
+
       # Details about why the charge status was updated.
       sig { returns(T.nilable(String)) }
       attr_accessor :reason
@@ -41,6 +44,7 @@ module Straddle
 
       sig do
         params(
+          id: String,
           reason: T.nilable(String),
           correlation_id: String,
           idempotency_key: String,
@@ -50,6 +54,7 @@ module Straddle
         ).returns(T.attached_class)
       end
       def self.new(
+        id:,
         # Details about why the charge status was updated.
         reason: nil,
         correlation_id: nil,
@@ -63,6 +68,7 @@ module Straddle
       sig do
         override.returns(
           {
+            id: String,
             reason: T.nilable(String),
             correlation_id: String,
             idempotency_key: String,

data/rbi/straddle/models/charge_unmask_params.rbi

@@ -11,6 +11,9 @@ module Straddle
           T.any(Straddle::ChargeUnmaskParams, Straddle::Internal::AnyHash)
         end
 
+      sig { returns(String) }
+      attr_accessor :id
+
       sig { returns(T.nilable(String)) }
       attr_reader :correlation_id
 
@@ -31,6 +34,7 @@ module Straddle
 
       sig do
         params(
+          id: String,
           correlation_id: String,
           request_id: String,
           straddle_account_id: String,
@@ -38,6 +42,7 @@ module Straddle
         ).returns(T.attached_class)
       end
       def self.new(
+        id:,
         correlation_id: nil,
         request_id: nil,
         straddle_account_id: nil,
@@ -48,6 +53,7 @@ module Straddle
       sig do
         override.returns(
           {
+            id: String,
             correlation_id: String,
             request_id: String,
             straddle_account_id: String,