stripe 10.1.0 → 12.6.0

data/lib/stripe/api_operations/request.rb

@@ -5,14 +5,14 @@ module Stripe
     module Request
       module ClassMethods
         def execute_resource_request(method, url,
-                                     params = {}, opts = {})
+                                     params = {}, opts = {}, usage = [])
           execute_resource_request_internal(
-            :execute_request, method, url, params, opts
+            :execute_request, method, url, params, opts, usage
           )
         end
 
         def execute_resource_request_stream(method, url,
-                                            params = {}, opts = {},
+                                            params = {}, opts = {}, usage = [],
                                             &read_body_chunk_block)
           execute_resource_request_internal(
             :execute_request_stream,
@@ -20,18 +20,19 @@ module Stripe
             url,
             params,
             opts,
+            usage,
             &read_body_chunk_block
           )
         end
 
-        private def request_stripe_object(method:, path:, params:, opts: {})
-          resp, opts = execute_resource_request(method, path, params, opts)
-          Util.convert_to_stripe_object_with_params(resp.data, params, opts)
+        private def request_stripe_object(method:, path:, params:, opts: {}, usage: [])
+          resp, opts = execute_resource_request(method, path, params, opts, usage)
+          Util.convert_to_stripe_object_with_params(resp.data, params, opts, resp)
         end
 
         private def execute_resource_request_internal(client_request_method_sym,
                                                       method, url,
-                                                      params, opts,
+                                                      params, opts, usage,
                                                       &read_body_chunk_block)
           params ||= {}
 
@@ -53,7 +54,7 @@ module Stripe
             client_request_method_sym,
             method, url,
             api_base: api_base, api_key: api_key,
-            headers: headers, params: params,
+            headers: headers, params: params, usage: usage,
             &read_body_chunk_block
           )
 
@@ -66,6 +67,7 @@ module Stripe
           [resp, opts_to_persist]
         end
 
+        # TODO: (major)
         # This method used to be called `request`, but it's such a short name
         # that it eventually conflicted with the name of a field on an API
         # resource (specifically, `Event#request`), so it was renamed to
@@ -76,6 +78,8 @@ module Stripe
         # place for backwards compatibility. Consider removing it on the next
         # major.
         alias request execute_resource_request
+        extend Gem::Deprecate
+        deprecate :request, "Stripe.raw_request", 2024, 7
 
         private def error_on_non_string_user_opts(opts)
           Util::OPTS_USER_SPECIFIED.each do |opt|
@@ -87,7 +91,7 @@ module Stripe
 
             raise ArgumentError,
                   "request option '#{opt}' should be a string value " \
-                    "(was a #{val.class})"
+                  "(was a #{val.class})"
           end
         end
 
@@ -96,14 +100,12 @@ module Stripe
 
           raise ArgumentError,
                 "request params should be either a Hash or nil " \
-                  "(was a #{params.class})"
+                "(was a #{params.class})"
         end
 
         private def warn_on_opts_in_params(params)
           Util::OPTS_USER_SPECIFIED.each do |opt|
-            if params.key?(opt)
-              warn("WARNING: '#{opt}' should be in opts instead of params.")
-            end
+            warn("WARNING: '#{opt}' should be in opts instead of params.") if params.key?(opt)
           end
         end
       end
@@ -113,9 +115,9 @@ module Stripe
       end
 
       protected def execute_resource_request(method, url,
-                                             params = {}, opts = {})
+                                             params = {}, opts = {}, usage = [])
         opts = @opts.merge(Util.normalize_opts(opts))
-        self.class.execute_resource_request(method, url, params, opts)
+        self.class.execute_resource_request(method, url, params, opts, usage)
       end
 
       protected def execute_resource_request_stream(method, url,
@@ -127,13 +129,15 @@ module Stripe
         )
       end
 
-      private def request_stripe_object(method:, path:, params:, opts: {})
-        resp, opts = execute_resource_request(method, path, params, opts)
-        Util.convert_to_stripe_object_with_params(resp.data, params, opts)
+      private def request_stripe_object(method:, path:, params:, opts: {}, usage: [])
+        resp, opts = execute_resource_request(method, path, params, opts, usage)
+        Util.convert_to_stripe_object_with_params(resp.data, params, opts, resp)
       end
 
       # See notes on `alias` above.
       alias request execute_resource_request
+      extend Gem::Deprecate
+      deprecate :request, "Stripe.raw_request", 2024, 7
     end
   end
 end

data/lib/stripe/api_operations/save.rb

@@ -19,9 +19,7 @@ module Stripe
         #   {APIOperations::Request.execute_resource_request}.
         def update(id, params = {}, opts = {})
           params.each_key do |k|
-            if protected_fields.include?(k)
-              raise ArgumentError, "Cannot update protected field: #{k}"
-            end
+            raise ArgumentError, "Cannot update protected field: #{k}" if protected_fields.include?(k)
           end
 
           request_stripe_object(
@@ -64,17 +62,17 @@ module Stripe
 
         values = serialize_params(self).merge(params)
 
-        # note that id gets removed here our call to #url above has already
+        # Please note that id gets removed here our call to #url above has already
         # generated a uri for this object with an identifier baked in
         values.delete(:id)
 
-        resp, opts = execute_resource_request(:post, save_url, values, opts)
-        initialize_from(resp.data, opts)
+        resp, opts = execute_resource_request(:post, save_url, values, opts, ["save"])
+        initialize_from(resp.data, opts, resp)
       end
       extend Gem::Deprecate
-      deprecate :save, "the `update` class method (for examples"\
-                " see https://github.com/stripe/stripe-ruby"\
-                "/wiki/Migration-guide-for-v8)", 2022, 11
+      deprecate :save, "the `update` class method (for examples " \
+                       "see https://github.com/stripe/stripe-ruby" \
+                       "/wiki/Migration-guide-for-v8)", 2022, 11
 
       def self.included(base)
         # Set `metadata` as additive so that when it's set directly we remember

data/lib/stripe/api_operations/search.rb

@@ -2,6 +2,8 @@
 
 module Stripe
   module APIOperations
+    # The _search method via API Operations is deprecated.
+    # Please use the search method from within the resource instead.
     module Search
       def _search(search_url, filters = {}, opts = {})
         request_stripe_object(
@@ -11,6 +13,9 @@ module Stripe
           opts: opts
         )
       end
+
+      extend Gem::Deprecate
+      deprecate :_search, "request_stripe_object", 2024, 1
     end
   end
 end

data/lib/stripe/api_operations/singleton_save.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Stripe
+  module APIOperations
+    module SingletonSave
+      module ClassMethods
+        # Updates a singleton API resource
+        #
+        # Updates the identified resource with the passed in parameters.
+        #
+        # ==== Attributes
+        #
+        # * +params+ - A hash of parameters to pass to the API
+        # * +opts+ - A Hash of additional options (separate from the params /
+        #   object values) to be added to the request. E.g. to allow for an
+        #   idempotency_key to be passed in the request headers, or for the
+        #   api_key to be overwritten. See
+        #   {APIOperations::Request.execute_resource_request}.
+        def update(params = {}, opts = {})
+          params.each_key do |k|
+            raise ArgumentError, "Cannot update protected field: #{k}" if protected_fields.include?(k)
+          end
+
+          request_stripe_object(
+            method: :post,
+            path: resource_url,
+            params: params,
+            opts: opts
+          )
+        end
+      end
+
+      # The `save` method is DEPRECATED and will be removed in a future major
+      # version of the library. Use the `update` method on the resource instead.
+      #
+      # Updates a singleton API resource.
+      #
+      # If the resource doesn't yet have an assigned ID and the resource is one
+      # that can be created, then the method attempts to create the resource.
+      # The resource is updated otherwise.
+      #
+      # ==== Attributes
+      #
+      # * +params+ - Overrides any parameters in the resource's serialized data
+      #   and includes them in the create or update. If +:req_url:+ is included
+      #   in the list, it overrides the update URL used for the create or
+      #   update.
+      # * +opts+ - A Hash of additional options (separate from the params /
+      #   object values) to be added to the request. E.g. to allow for an
+      #   idempotency_key to be passed in the request headers, or for the
+      #   api_key to be overwritten. See
+      #   {APIOperations::Request.execute_resource_request}.
+      def save(params = {}, opts = {})
+        # We started unintentionally (sort of) allowing attributes sent to
+        # +save+ to override values used during the update. So as not to break
+        # the API, this makes that official here.
+        update_attributes(params)
+
+        # Now remove any parameters that look like object attributes.
+        params = params.reject { |k, _| respond_to?(k) }
+
+        values = serialize_params(self).merge(params)
+
+        resp, opts = execute_resource_request(:post, resource_url, values, opts, ["save"])
+        initialize_from(resp.data, opts, resp)
+      end
+      extend Gem::Deprecate
+      deprecate :save, "the `update` class method (for examples " \
+                       "see https://github.com/stripe/stripe-ruby" \
+                       "/wiki/Migration-guide-for-v8)", 2022, 11
+
+      def self.included(base)
+        # Set `metadata` as additive so that when it's set directly we remember
+        # to clear keys that may have been previously set by sending empty
+        # values for them.
+        #
+        # It's possible that not every object with `Save` has `metadata`, but
+        # it's a close enough heuristic, and having this option set when there
+        # is no `metadata` field is not harmful.
+        base.additive_object_param(:metadata)
+
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/stripe/api_resource.rb

@@ -11,6 +11,15 @@ module Stripe
     # for example, where this is allowed.
     attr_accessor :save_with_parent
 
+    # TODO: (major) Remove OBJECT_NAME and stop using const_get here
+    # This is a workaround to avoid breaking users who have defined their own
+    # APIResource subclasses with a custom OBJECT_NAME. We should never fallback
+    # on this case otherwise.
+    OBJECT_NAME = ""
+    def self.object_name
+      const_get(:OBJECT_NAME)
+    end
+
     def self.class_name
       name.split("::")[-1]
     end
@@ -23,7 +32,7 @@ module Stripe
       end
       # Namespaces are separated in object names with periods (.) and in URLs
       # with forward slashes (/), so replace the former with the latter.
-      "/v1/#{self::OBJECT_NAME.downcase.tr('.', '/')}s"
+      "/v1/#{object_name.downcase.tr('.', '/')}s"
     end
 
     # A metaprogramming call that specifies that a field of a resource can be
@@ -80,7 +89,7 @@ module Stripe
     def refresh
       resp, opts = execute_resource_request(:get, resource_url,
                                             @retrieve_params)
-      initialize_from(resp.data, opts)
+      initialize_from(resp.data, opts, resp)
     end
 
     def self.retrieve(id, opts = {})
@@ -95,9 +104,9 @@ module Stripe
 
       # If we're getting back this thing, update; otherwise, instantiate.
       if Util.object_name_matches_class?(resp.data[:object], self.class)
-        initialize_from(resp.data, opts)
+        initialize_from(resp.data, opts, resp)
       else
-        Util.convert_to_stripe_object_with_params(resp.data, params, opts)
+        Util.convert_to_stripe_object_with_params(resp.data, params, opts, resp)
       end
     end
 

data/lib/stripe/api_resource_test_helpers.rb

@@ -14,6 +14,10 @@ module Stripe
       @resource = resource
     end
 
+    def self.resource_class
+      nil
+    end
+
     # Adds a custom method to a test helper. This is used to add support for
     # non-CRUDL API requests, e.g. capturing charges. custom_method takes the
     # following parameters:
@@ -27,12 +31,12 @@ module Stripe
     # adds a `capture` class method to the resource class that, when called,
     # will send a POST request to `/v1/<object_name>/capture`.
     def self.custom_method(name, http_verb:, http_path: nil)
-      Util.custom_method self::RESOURCE_CLASS, self, name, http_verb, http_path
+      Util.custom_method resource_class, self, name, http_verb, http_path
     end
 
     def self.resource_url
-      "/v1/test_helpers/"\
-      "#{self::RESOURCE_CLASS::OBJECT_NAME.downcase.tr('.', '/')}s"
+      "/v1/test_helpers/" \
+        "#{resource_class.object_name.downcase.tr('.', '/')}s"
     end
 
     def resource_url

data/lib/stripe/api_version.rb

@@ -3,6 +3,6 @@
 
 module Stripe
   module ApiVersion
-    CURRENT = "2023-10-16"
+    CURRENT = "2024-06-20"
   end
 end

data/lib/stripe/connection_manager.rb

@@ -157,9 +157,7 @@ module Stripe
 
       connection.open_timeout = config.open_timeout
       connection.read_timeout = config.read_timeout
-      if connection.respond_to?(:write_timeout=)
-        connection.write_timeout = config.write_timeout
-      end
+      connection.write_timeout = config.write_timeout if connection.respond_to?(:write_timeout=)
 
       connection.use_ssl = uri.scheme == "https"
 
@@ -192,9 +190,9 @@ module Stripe
 
       @verify_ssl_warned = true
       warn("WARNING: Running without SSL cert verification. " \
-        "You should never do this in production. " \
-        "Execute `Stripe.verify_ssl_certs = true` to enable " \
-        "verification.")
+           "You should never do this in production. " \
+           "Execute `Stripe.verify_ssl_certs = true` to enable " \
+           "verification.")
     end
   end
 end

data/lib/stripe/errors.rb

@@ -4,22 +4,14 @@ module Stripe
   # StripeError is the base error from which all other more specific Stripe
   # errors derive.
   class StripeError < StandardError
-    attr_reader :message
+    attr_reader :message, :code, :error, :http_body, :http_headers, :http_status, :json_body, :request_id
 
     # Response contains a StripeResponse object that has some basic information
     # about the response that conveyed the error.
-    attr_accessor :response
-
-    attr_reader :code
-    attr_reader :error
-    attr_reader :http_body
-    attr_reader :http_headers
-    attr_reader :http_status
-    attr_reader :json_body # equivalent to #data
-    attr_reader :request_id
+    attr_accessor :response # equivalent to #data
 
     # Initializes a StripeError.
-    def initialize(message = nil, http_status: nil, http_body: nil,
+    def initialize(message = nil, http_status: nil, http_body: nil, # rubocop:todo Lint/MissingSuper
                    json_body: nil, http_headers: nil, code: nil)
       @message = message
       @http_status = http_status

data/lib/stripe/instrumentation.rb

@@ -4,8 +4,7 @@ module Stripe
   class Instrumentation
     # Event emitted on `request_begin` callback.
     class RequestBeginEvent
-      attr_reader :method
-      attr_reader :path
+      attr_reader :method, :path
 
       # Arbitrary user-provided data in the form of a Ruby hash that's passed
       # from subscribers on `request_begin` to subscribers on `request_end`.
@@ -27,16 +26,8 @@ module Stripe
 
     # Event emitted on `request_end` callback.
     class RequestEndEvent
-      attr_reader :duration
-      attr_reader :http_status
-      attr_reader :method
-      attr_reader :num_retries
-      attr_reader :path
-      attr_reader :request_id
-      attr_reader :response_header
-      attr_reader :response_body
-      attr_reader :request_header
-      attr_reader :request_body
+      attr_reader :duration, :http_status, :method, :num_retries, :path, :request_id, :response_header, :response_body,
+                  :request_header, :request_body
 
       # Arbitrary user-provided data in the form of a Ruby hash that's passed
       # from subscribers on `request_begin` to subscribers on `request_end`.
@@ -62,12 +53,7 @@ module Stripe
     end
 
     class RequestContext
-      attr_reader :duration
-      attr_reader :method
-      attr_reader :path
-      attr_reader :request_id
-      attr_reader :body
-      attr_reader :header
+      attr_reader :duration, :method, :path, :request_id, :body, :header
 
       def initialize(duration:, context:, header:)
         @duration = duration
@@ -80,9 +66,7 @@ module Stripe
     end
 
     class ResponseContext
-      attr_reader :http_status
-      attr_reader :body
-      attr_reader :header
+      attr_reader :http_status, :body, :header
 
       def initialize(http_status:, response:)
         @http_status = http_status

data/lib/stripe/list_object.rb

@@ -8,6 +8,9 @@ module Stripe
     include Stripe::APIOperations::Create
 
     OBJECT_NAME = "list"
+    def self.object_name
+      "list"
+    end
 
     # This accessor allows a `ListObject` to inherit various filters that were
     # given to a predecessor. This allows for things like consistent limits,

data/lib/stripe/multipart_encoder.rb

@@ -106,22 +106,22 @@ module Stripe
     end
 
     private def write_field(name, data, filename:)
-      if !@first_field
-        @body << "\r\n"
-      else
+      if @first_field
         @first_field = false
+      else
+        @body << "\r\n"
       end
 
       @body << "--#{@boundary}\r\n"
 
       if filename
-        @body << %(Content-Disposition: form-data) +
+        @body << (%(Content-Disposition: form-data) +
                  %(; name="#{escape(name.to_s)}") +
-                 %(; filename="#{escape(filename)}"\r\n)
+                 %(; filename="#{escape(filename)}"\r\n))
         @body << %(Content-Type: application/octet-stream\r\n)
       else
-        @body << %(Content-Disposition: form-data) +
-                 %(; name="#{escape(name.to_s)}"\r\n)
+        @body << (%(Content-Disposition: form-data) +
+                 %(; name="#{escape(name.to_s)}"\r\n))
       end
 
       @body << "\r\n"

data/lib/stripe/oauth.rb

@@ -18,12 +18,12 @@ module Stripe
       client_id = params[:client_id] || Stripe.client_id
       unless client_id
         raise AuthenticationError, "No client_id provided. " \
-          'Set your client_id using "Stripe.client_id = <CLIENT-ID>". ' \
-          "You can find your client_ids in your Stripe dashboard at " \
-          "https://dashboard.stripe.com/account/applications/settings, " \
-          "after registering your account as a platform. See " \
-          "https://stripe.com/docs/connect/standalone-accounts for details, " \
-          "or email support@stripe.com if you have any questions."
+                                   'Set your client_id using "Stripe.client_id = <CLIENT-ID>". ' \
+                                   "You can find your client_ids in your Stripe dashboard at " \
+                                   "https://dashboard.stripe.com/account/applications/settings, " \
+                                   "after registering your account as a platform. See " \
+                                   "https://stripe.com/docs/connect/standalone-accounts for details, " \
+                                   "or email support@stripe.com if you have any questions."
       end
       client_id
     end