straddle 0.4.0 → 1.0.0

data/lib/straddle/client.rb

@@ -15,97 +15,91 @@ module Straddle
     # Default max retry delay in seconds.
     DEFAULT_MAX_RETRY_DELAY = 8.0
 
-    # rubocop:disable Style/MutableConstant
-    # @type [Hash{Symbol=>String}]
-    ENVIRONMENTS = {sandbox: "https://sandbox.straddle.com", production: "https://production.straddle.com"}
-    # rubocop:enable Style/MutableConstant
-
-    # Use your Straddle API Key in the Authorization header as Bearer <token> to
-    # authorize API requests.
+    # Send the API key as a bearer token in the `Authorization` header.
     # @return [String]
-    attr_reader :api_key
+    attr_reader :bearer
+
+    # Secret used to verify incoming webhook signatures.
+    # @return [String, nil]
+    attr_reader :webhook_secret
+
+    # Accounts represent businesses that use Straddle through a platform.
+    # @return [Straddle::Resources::Accounts]
+    attr_reader :accounts
+
+    # Capability requests change the payment, customer, and consent types available to
+    # an account.
+    # @return [Straddle::Resources::CapabilityRequests]
+    attr_reader :capability_requests
+
+    # Linked bank accounts connect external bank accounts to an account or platform
+    # for charges, payouts, or billing.
+    # @return [Straddle::Resources::LinkedBankAccounts]
+    attr_reader :linked_bank_accounts
+
+    # Organizations group related Straddle accounts.
+    # @return [Straddle::Resources::Organizations]
+    attr_reader :organizations
 
-    # @return [Straddle::Resources::Embed]
-    attr_reader :embed
+    # Representatives are people associated with a business account for ownership,
+    # control, or authorization purposes.
+    # @return [Straddle::Resources::Representatives]
+    attr_reader :representatives
 
-    # 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.
+    # Bridge connects customer bank accounts and creates paykeys from supported
+    # provider tokens or bank account details.
     # @return [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.
+    # Customers are individuals or businesses that send or receive payments through
+    # your integration.
     # @return [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.
+    # A paykey links a verified customer to a bank account without exposing bank
+    # account details. Use a paykey to create charges and payouts.
     # @return [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.
+    # Charges debit a customer's bank account through a paykey.
     # @return [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.
+    # Funding events group charge and payout activity into transfers between Straddle
+    # and your linked bank account.
     # @return [Straddle::Resources::FundingEvents]
     attr_reader :funding_events
 
-    # Payments provide endpoints to filter both Charges and Payouts with multiple
-    # different parameters.
+    # Payments provide a combined view of charges and payouts.
     # @return [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.
+    # Payouts send money to a customer's bank account through a paykey.
     # @return [Straddle::Resources::Payouts]
     attr_reader :payouts
 
-    # @return [Straddle::Resources::Reports]
-    attr_reader :reports
+    # Account settings define payment limits, capabilities, statement details, and
+    # policy controls for an account.
+    # @return [Straddle::Resources::AccountSettings]
+    attr_reader :account_settings
+
+    # @return [Straddle::Resources::Webhooks]
+    attr_reader :webhooks
 
     # @api private
     #
     # @return [Hash{String=>String}]
     private def auth_headers
-      return {} if @api_key.nil?
-
-      {"authorization" => "Bearer #{@api_key}"}
+      {"authorization" => "Bearer #{@bearer}"}
     end
 
     # Creates and returns a new client for interacting with the API.
     #
-    # @param api_key [String, nil] Use your Straddle API Key in the Authorization header as Bearer <token> to
-    # authorize API requests. Defaults to `ENV["STRADDLE_API_KEY"]`
-    #
-    # @param environment [:sandbox, :production, nil] Specifies the environment to use for the API.
+    # @param bearer [String, nil] Send the API key as a bearer token in the `Authorization` header. Defaults to
+    # `ENV["BEARER"]`
     #
-    # Each environment maps to a different base URL:
-    #
-    # - `sandbox` corresponds to `https://sandbox.straddle.com`
-    # - `production` corresponds to `https://production.straddle.com`
+    # @param webhook_secret [String, nil] Secret used to verify incoming webhook signatures. Defaults to
+    # `ENV["STRADDLE_WEBHOOK_SECRET"]`
     #
     # @param base_url [String, nil] Override the default base URL for the API, e.g.,
     # `"https://api.example.com/v2/"`. Defaults to `ENV["STRADDLE_BASE_URL"]`
@@ -118,34 +112,48 @@ module Straddle
     #
     # @param max_retry_delay [Float]
     def initialize(
-      api_key: ENV["STRADDLE_API_KEY"],
-      environment: nil,
+      bearer: ENV["BEARER"],
+      webhook_secret: ENV["STRADDLE_WEBHOOK_SECRET"],
       base_url: ENV["STRADDLE_BASE_URL"],
       max_retries: self.class::DEFAULT_MAX_RETRIES,
       timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
       initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
       max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
     )
-      base_url ||= Straddle::Client::ENVIRONMENTS.fetch(environment&.to_sym || :production) do
-        message = "environment must be one of #{Straddle::Client::ENVIRONMENTS.keys}, got #{environment}"
-        raise ArgumentError.new(message)
-      end
-
-      if api_key.nil?
-        raise ArgumentError.new("api_key is required, and can be set via environ: \"STRADDLE_API_KEY\"")
+      base_url ||= "https://sandbox.straddle.com"
+
+      raise ArgumentError.new("bearer is required, and can be set via environ: \"BEARER\"") if bearer.nil?
+
+      headers = {}
+      custom_headers_env = ENV["STRADDLE_CUSTOM_HEADERS"]
+      unless custom_headers_env.nil?
+        parsed = {}
+        custom_headers_env
+          .split("\n")
+          .each do |line|
+            colon = line.index(":")
+            parsed[line[0...colon].strip] = line[(colon + 1)..].strip unless colon.nil?
+          end
+        headers = parsed.merge(headers)
       end
 
-      @api_key = api_key.to_s
+      @bearer = bearer.to_s
+      @webhook_secret = webhook_secret&.to_s
 
       super(
         base_url: base_url,
         timeout: timeout,
         max_retries: max_retries,
         initial_retry_delay: initial_retry_delay,
-        max_retry_delay: max_retry_delay
+        max_retry_delay: max_retry_delay,
+        headers: headers
       )
 
-      @embed = Straddle::Resources::Embed.new(client: self)
+      @accounts = Straddle::Resources::Accounts.new(client: self)
+      @capability_requests = Straddle::Resources::CapabilityRequests.new(client: self)
+      @linked_bank_accounts = Straddle::Resources::LinkedBankAccounts.new(client: self)
+      @organizations = Straddle::Resources::Organizations.new(client: self)
+      @representatives = Straddle::Resources::Representatives.new(client: self)
       @bridge = Straddle::Resources::Bridge.new(client: self)
       @customers = Straddle::Resources::Customers.new(client: self)
       @paykeys = Straddle::Resources::Paykeys.new(client: self)
@@ -153,7 +161,8 @@ module Straddle
       @funding_events = Straddle::Resources::FundingEvents.new(client: self)
       @payments = Straddle::Resources::Payments.new(client: self)
       @payouts = Straddle::Resources::Payouts.new(client: self)
-      @reports = Straddle::Resources::Reports.new(client: self)
+      @account_settings = Straddle::Resources::AccountSettings.new(client: self)
+      @webhooks = Straddle::Resources::Webhooks.new(client: self)
     end
   end
 end

data/lib/straddle/errors.rb

@@ -133,16 +133,15 @@ module Straddle
       #
       # @return [self]
       def self.for(url:, status:, headers:, body:, request:, response:, message: nil)
-        kwargs =
-          {
-            url: url,
-            status: status,
-            headers: headers,
-            body: body,
-            request: request,
-            response: response,
-            message: message
-          }
+        kwargs = {
+          url: url,
+          status: status,
+          headers: headers,
+          body: body,
+          request: request,
+          response: response,
+          message: message
+        }
 
         case status
         in 400
@@ -159,7 +158,7 @@ module Straddle
           Straddle::Errors::UnprocessableEntityError.new(**kwargs)
         in 429
           Straddle::Errors::RateLimitError.new(**kwargs)
-        in (500..)
+        in 500.. then
           Straddle::Errors::InternalServerError.new(**kwargs)
         else
           Straddle::Errors::APIStatusError.new(**kwargs)

data/lib/straddle/internal/transport/base_client.rb

@@ -13,15 +13,14 @@ module Straddle
         MAX_REDIRECTS = 20
 
         # rubocop:disable Style/MutableConstant
-        PLATFORM_HEADERS =
-          {
-            "x-stainless-arch" => Straddle::Internal::Util.arch,
-            "x-stainless-lang" => "ruby",
-            "x-stainless-os" => Straddle::Internal::Util.os,
-            "x-stainless-package-version" => Straddle::VERSION,
-            "x-stainless-runtime" => ::RUBY_ENGINE,
-            "x-stainless-runtime-version" => ::RUBY_ENGINE_VERSION
-          }
+        PLATFORM_HEADERS = {
+          "x-scalar-arch" => Straddle::Internal::Util.arch,
+          "x-scalar-lang" => "ruby",
+          "x-scalar-os" => Straddle::Internal::Util.os,
+          "x-scalar-package-version" => Straddle::VERSION,
+          "x-scalar-runtime" => ::RUBY_ENGINE,
+          "x-scalar-runtime-version" => ::RUBY_ENGINE_VERSION
+        }
         # rubocop:enable Style/MutableConstant
 
         class << self
@@ -31,7 +30,7 @@ module Straddle
           #
           # @raise [ArgumentError]
           def validate!(req)
-            keys = [:method, :path, :query, :headers, :body, :unwrap, :page, :stream, :model, :options]
+            keys = %i[method path query headers body unwrap page stream model options]
             case req
             in Hash
               req.each_key do |k|
@@ -55,7 +54,7 @@ module Straddle
             case [coerced, status]
             in [true | false, _]
               coerced
-            in [_, 408 | 409 | 429 | (500..)]
+            in [_, 408 | 409 | 429 | 500..]
               # retry on:
               # 408: timeouts
               # 409: locks
@@ -144,9 +143,9 @@ module Straddle
           # @param stream [Enumerable<String>, nil]
           def reap_connection!(status, stream:)
             case status
-            in (..199) | (300..499)
+            in ..199 | 300..499
               stream&.each { next }
-            in Straddle::Errors::APIConnectionError | (500..)
+            in Straddle::Errors::APIConnectionError | 500.. then
               Straddle::Internal::Util.close_fused!(stream)
             else
             end
@@ -197,15 +196,16 @@ module Straddle
           idempotency_header: nil
         )
           @requester = Straddle::Internal::Transport::PooledNetRequester.new
-          @headers = Straddle::Internal::Util.normalized_headers(
-            self.class::PLATFORM_HEADERS,
-            {
-              "accept" => "application/json",
-              "content-type" => "application/json",
-              "user-agent" => user_agent
-            },
-            headers
-          )
+          @headers =
+            Straddle::Internal::Util.normalized_headers(
+              self.class::PLATFORM_HEADERS,
+              {
+                "accept" => "application/json",
+                "content-type" => "application/json",
+                "user-agent" => user_agent
+              },
+              headers
+            )
           @base_url_components = Straddle::Internal::Util.parse_uri(base_url)
           @base_url = Straddle::Internal::Util.unparse_uri(@base_url_components)
           @idempotency_header = idempotency_header&.to_s&.downcase
@@ -228,7 +228,7 @@ module Straddle
         # @api private
         #
         # @return [String]
-        private def generate_idempotency_key = "stainless-ruby-retry-#{SecureRandom.uuid}"
+        private def generate_idempotency_key = "scalar-ruby-retry-#{SecureRandom.uuid}"
 
         # @api private
         #
@@ -274,27 +274,23 @@ module Straddle
 
           query = Straddle::Internal::Util.deep_merge(req[:query].to_h, opts[:extra_query].to_h)
 
-          headers = Straddle::Internal::Util.normalized_headers(
-            @headers,
-            auth_headers,
-            req[:headers].to_h,
-            opts[:extra_headers].to_h
-          )
+          headers =
+            Straddle::Internal::Util.normalized_headers(
+              @headers,
+              auth_headers,
+              req[:headers].to_h,
+              opts[:extra_headers].to_h
+            )
 
-          if @idempotency_header &&
-             !headers.key?(@idempotency_header) &&
+          if @idempotency_header && !headers.key?(@idempotency_header) &&
              (!Net::HTTP::IDEMPOTENT_METHODS_.include?(method.to_s.upcase) || opts.key?(:idempotency_key))
             headers[@idempotency_header] = opts.fetch(:idempotency_key) { generate_idempotency_key }
           end
 
-          unless headers.key?("x-stainless-retry-count")
-            headers["x-stainless-retry-count"] = "0"
-          end
+          headers["x-scalar-retry-count"] = "0" unless headers.key?("x-scalar-retry-count")
 
           timeout = opts.fetch(:timeout, @timeout).to_f.clamp(0..)
-          unless headers.key?("x-stainless-timeout") || timeout.zero?
-            headers["x-stainless-timeout"] = timeout.to_s
-          end
+          headers["x-scalar-timeout"] = timeout.to_s unless headers.key?("x-scalar-timeout") || timeout.zero?
 
           headers.reject! { |_, v| v.to_s.empty? }
 
@@ -306,10 +302,16 @@ module Straddle
               Straddle::Internal::Util.deep_merge(*[req[:body], opts[:extra_body]].compact)
             end
 
-          url = Straddle::Internal::Util.join_parsed_uri(
-            @base_url_components,
-            {**req, path: path, query: query}
-          )
+          # Generated methods always pass `req[:body]` for operations that define a
+          # request body, so only elide the content-type header when the operation
+          # has no body at all, not when an optional body param was omitted.
+          headers.delete("content-type") if body.nil? && !req.key?(:body)
+
+          url =
+            Straddle::Internal::Util.join_parsed_uri(
+              @base_url_components,
+              {**req, path: path, query: query}
+            )
           headers, encoded = Straddle::Internal::Util.encode_content(headers, body)
           {
             method: method,
@@ -335,11 +337,12 @@ module Straddle
           retry_header = headers["retry-after"]
           return span if (span = Float(retry_header, exception: false))
 
-          span = retry_header&.then do
-            Time.httpdate(_1) - Time.now
-          rescue ArgumentError
-            nil
-          end
+          span =
+            retry_header&.then do
+              Time.httpdate(_1) - Time.now
+            rescue ArgumentError
+              nil
+            end
           return span if span
 
           scale = retry_count**2
@@ -375,9 +378,7 @@ module Straddle
           url, headers, max_retries, timeout = request.fetch_values(:url, :headers, :max_retries, :timeout)
           input = {**request.except(:timeout), deadline: Straddle::Internal::Util.monotonic_secs + timeout}
 
-          if send_retry_header
-            headers["x-stainless-retry-count"] = retry_count.to_s
-          end
+          headers["x-scalar-retry-count"] = retry_count.to_s if send_retry_header
 
           begin
             status, response, stream = @requester.execute(input)
@@ -407,11 +408,12 @@ module Straddle
           in Straddle::Errors::APIConnectionError if retry_count >= max_retries
             raise status
           in (400..) if retry_count >= max_retries || !self.class.should_retry?(status, headers: headers)
-            decoded = Kernel.then do
-              Straddle::Internal::Util.decode_content(headers, stream: stream, suppress_error: true)
-            ensure
-              self.class.reap_connection!(status, stream: stream)
-            end
+            decoded =
+              Kernel.then do
+                Straddle::Internal::Util.decode_content(headers, stream: stream, suppress_error: true)
+              ensure
+                self.class.reap_connection!(status, stream: stream)
+              end
 
             raise Straddle::Errors::APIStatusError.for(
               url: url,
@@ -421,7 +423,7 @@ module Straddle
               request: nil,
               response: response
             )
-          in (400..) | Straddle::Errors::APIConnectionError
+          in 400.. | Straddle::Errors::APIConnectionError
             self.class.reap_connection!(status, stream: stream)
 
             delay = retry_delay(response || {}, retry_count: retry_count)
@@ -485,18 +487,14 @@ module Straddle
           url = request.fetch(:url)
 
           # Don't send the current retry count in the headers if the caller modified the header defaults.
-          send_retry_header = request.fetch(:headers)["x-stainless-retry-count"] == "0"
-          status, response, stream = send_request(
-            request,
-            redirect_count: 0,
-            retry_count: 0,
-            send_retry_header: send_retry_header
-          )
+          send_retry_header = request.fetch(:headers)["x-scalar-retry-count"] == "0"
+          status, response, stream =
+            send_request(request, redirect_count: 0, retry_count: 0, send_retry_header: send_retry_header)
 
           headers = Straddle::Internal::Util.normalized_headers(response.each_header.to_h)
           decoded = Straddle::Internal::Util.decode_content(headers, stream: stream)
           case req
-          in {stream: Class => st}
+          in stream: Class => st
             st.new(
               model: model,
               url: url,
@@ -506,7 +504,7 @@ module Straddle
               unwrap: unwrap,
               stream: decoded
             )
-          in {page: Class => page}
+          in page: Class => page
             page.new(client: self, req: req, headers: headers, page_data: decoded)
           else
             unwrapped = Straddle::Internal::Util.dig(decoded, unwrap)
@@ -529,26 +527,25 @@ module Straddle
               method: Symbol,
               path: T.any(String, T::Array[String]),
               query: T.nilable(T::Hash[String, T.nilable(T.any(T::Array[String], String))]),
-              headers: T.nilable(
-                T::Hash[String,
-                        T.nilable(
-                          T.any(
-                            String,
-                            Integer,
-                            T::Array[T.nilable(T.any(String, Integer))]
-                          )
-                        )]
-              ),
+              headers:
+                T.nilable(
+                  T::Hash[
+                    String,
+                    T.nilable(T.any(String, Integer, T::Array[T.nilable(T.any(String, Integer))]))
+                  ]
+                ),
               body: T.nilable(T.anything),
-              unwrap: T.nilable(
-                T.any(
-                  Symbol,
-                  Integer,
-                  T::Array[T.any(Symbol, Integer)],
-                  T.proc.params(arg0: T.anything).returns(T.anything)
-                )
-              ),
-              page: T.nilable(T::Class[Straddle::Internal::Type::BasePage[Straddle::Internal::Type::BaseModel]]),
+              unwrap:
+                T.nilable(
+                  T.any(
+                    Symbol,
+                    Integer,
+                    T::Array[T.any(Symbol, Integer)],
+                    T.proc.params(arg0: T.anything).returns(T.anything)
+                  )
+                ),
+              page:
+                T.nilable(T::Class[Straddle::Internal::Type::BasePage[Straddle::Internal::Type::BaseModel]]),
               stream: T.nilable(T::Class[T.anything]),
               model: T.nilable(Straddle::Internal::Type::Converter::Input),
               options: T.nilable(Straddle::RequestOptions::OrHash)