straddle 0.3.0 → 0.4.0

data/lib/straddle/resources/payments.rb

@@ -2,6 +2,8 @@
 
 module Straddle
   module Resources
+    # Payments provide endpoints to filter both Charges and Payouts with multiple
+    # different parameters.
     class Payments
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::PaymentListParams} for more details.
@@ -9,20 +11,22 @@ module Straddle
       # Search for payments, including `charges` and `payouts`, using a variety of
       # criteria. This endpoint supports advanced sorting and filtering options.
       #
-      # @overload list(customer_id: nil, default_page_size: nil, default_sort: nil, default_sort_order: nil, external_id: nil, funding_id: nil, max_amount: nil, max_created_at: nil, max_effective_at: nil, max_payment_date: nil, min_amount: nil, min_created_at: nil, min_effective_at: nil, min_payment_date: nil, page_number: nil, page_size: nil, paykey: nil, paykey_id: nil, payment_id: nil, payment_status: nil, payment_type: nil, search_text: nil, sort_by: nil, sort_order: nil, status_reason: nil, status_source: nil, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # @overload list(customer_id: nil, default_page_size: nil, default_sort: nil, default_sort_order: nil, external_id: nil, funding_id: nil, include_metadata: nil, max_amount: nil, max_created_at: nil, max_effective_at: nil, max_payment_date: nil, min_amount: nil, min_created_at: nil, min_effective_at: nil, min_payment_date: nil, page_number: nil, page_size: nil, paykey: nil, paykey_id: nil, payment_id: nil, payment_status: nil, payment_type: nil, search_text: nil, sort_by: nil, sort_order: nil, status_reason: nil, status_source: nil, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
       # @param customer_id [String] Query param: Search using the `customer_id` of a `charge` or `payout`.
       #
-      # @param default_page_size [Integer] Query param:
+      # @param default_page_size [Integer] Query param
       #
       # @param default_sort [Symbol, Straddle::Models::PaymentListParams::DefaultSort] Query param: The field to sort the results by.
       #
-      # @param default_sort_order [Symbol, Straddle::Models::PaymentListParams::DefaultSortOrder] Query param:
+      # @param default_sort_order [Symbol, Straddle::Models::PaymentListParams::DefaultSortOrder] Query param
       #
       # @param external_id [String] Query param: Search using the `external_id` of a `charge` or `payout`.
       #
       # @param funding_id [String] Query param: Search using the `funding_id` of a `charge` or `payout`.
       #
+      # @param include_metadata [Boolean] Query param: Include the metadata for payments in the returned data.
+      #
       # @param max_amount [Integer] Query param: Search using a maximum `amount` of a `charge` or `payout`.
       #
       # @param max_created_at [Time] Query param: Search using the latest `created_at` date of a `charge` or `payout`
@@ -57,7 +61,7 @@ module Straddle
       #
       # @param sort_by [Symbol, Straddle::Models::PaymentListParams::SortBy] Query param: The field to sort the results by.
       #
-      # @param sort_order [Symbol, Straddle::Models::PaymentListParams::SortOrder] Query param:
+      # @param sort_order [Symbol, Straddle::Models::PaymentListParams::SortOrder] Query param
       #
       # @param status_reason [Array<Symbol, Straddle::Models::PaymentListParams::StatusReason>] Query param: Reason for latest payment status change.
       #
@@ -75,7 +79,6 @@ module Straddle
       #
       # @see Straddle::Models::PaymentListParams
       def list(params = {})
-        parsed, options = Straddle::PaymentListParams.dump_request(params)
         query_params =
           [
             :customer_id,
@@ -84,6 +87,7 @@ module Straddle
             :default_sort_order,
             :external_id,
             :funding_id,
+            :include_metadata,
             :max_amount,
             :max_created_at,
             :max_effective_at,
@@ -105,10 +109,12 @@ module Straddle
             :status_reason,
             :status_source
           ]
+        parsed, options = Straddle::PaymentListParams.dump_request(params)
+        query = Straddle::Internal::Util.encode_query_params(parsed.slice(*query_params))
         @client.request(
           method: :get,
           path: "v1/payments",
-          query: parsed.slice(*query_params),
+          query: query,
           headers: parsed.except(*query_params).transform_keys(
             correlation_id: "correlation-id",
             request_id: "request-id",

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.
       #

data/lib/straddle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Straddle
-  VERSION = "0.3.0"
+  VERSION = "0.4.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"

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

@@ -296,11 +296,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
             }

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,