stripe 1.27.2 → 5.33.0

data/lib/stripe/api_operations/delete.rb

@@ -1,10 +1,38 @@
+# frozen_string_literal: true
+
 module Stripe
   module APIOperations
     module Delete
-      def delete(params={}, opts={})
-        opts = Util.normalize_opts(opts)
-        response, opts = request(:delete, url, params, opts)
-        refresh_from(response, opts)
+      module ClassMethods
+        # Deletes an API resource
+        #
+        # Deletes the identified resource with the passed in parameters.
+        #
+        # ==== Attributes
+        #
+        # * +id+ - ID of the resource to delete.
+        # * +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 delete(id, params = {}, opts = {})
+          resp, opts = execute_resource_request(:delete,
+                                                "#{resource_url}/#{id}",
+                                                params, opts)
+          Util.convert_to_stripe_object(resp.data, opts)
+        end
+      end
+
+      def delete(params = {}, opts = {})
+        resp, opts = execute_resource_request(:delete, resource_url,
+                                              params, opts)
+        initialize_from(resp.data, opts)
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
       end
     end
   end

data/lib/stripe/api_operations/list.rb

@@ -1,16 +1,18 @@
+# frozen_string_literal: true
+
 module Stripe
   module APIOperations
     module List
-      module ClassMethods
-        def all(filters={}, opts={})
-          opts = Util.normalize_opts(opts)
-          response, opts = request(:get, url, filters, opts)
-          Util.convert_to_stripe_object(response, opts)
-        end
-      end
+      def list(filters = {}, opts = {})
+        opts = Util.normalize_opts(opts)
+
+        resp, opts = execute_resource_request(:get, resource_url, filters, opts)
+        obj = ListObject.construct_from(resp.data, opts)
 
-      def self.included(base)
-        base.extend(ClassMethods)
+        # set filters so that we can fetch the same limit, expansions, and
+        # predicates when accessing the next and previous pages
+        obj.filters = filters.dup
+        obj
       end
     end
   end

data/lib/stripe/api_operations/nested_resource.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Stripe
+  module APIOperations
+    # Adds methods to help manipulate a subresource from its parent resource so
+    # that it's possible to do so from a static context (i.e. without a
+    # pre-existing collection of subresources on the parent).
+    #
+    # For example, a transfer gains the static methods for reversals so that the
+    # methods `.create_reversal`, `.retrieve_reversal`, `.update_reversal`,
+    # etc. all become available.
+    module NestedResource
+      def nested_resource_class_methods(resource, path: nil, operations: nil,
+                                        resource_plural: nil)
+        resource_plural ||= "#{resource}s"
+        path ||= resource_plural
+
+        raise ArgumentError, "operations array required" if operations.nil?
+
+        resource_url_method = :"#{resource}s_url"
+
+        define_singleton_method(resource_url_method) do |id, nested_id = nil|
+          url = "#{resource_url}/#{CGI.escape(id)}/#{CGI.escape(path)}"
+          url += "/#{CGI.escape(nested_id)}" unless nested_id.nil?
+          url
+        end
+
+        operations.each do |operation|
+          case operation
+          when :create
+            define_singleton_method(:"create_#{resource}") \
+              do |id, params = {}, opts = {}|
+                url = send(resource_url_method, id)
+                resp, opts = execute_resource_request(:post, url, params, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
+          when :retrieve
+            define_singleton_method(:"retrieve_#{resource}") \
+              do |id, nested_id, opts = {}|
+                url = send(resource_url_method, id, nested_id)
+                resp, opts = execute_resource_request(:get, url, {}, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
+          when :update
+            define_singleton_method(:"update_#{resource}") \
+              do |id, nested_id, params = {}, opts = {}|
+                url = send(resource_url_method, id, nested_id)
+                resp, opts = execute_resource_request(:post, url, params, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
+          when :delete
+            define_singleton_method(:"delete_#{resource}") \
+              do |id, nested_id, params = {}, opts = {}|
+                url = send(resource_url_method, id, nested_id)
+                resp, opts = execute_resource_request(:delete, url, params,
+                                                      opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
+          when :list
+            define_singleton_method(:"list_#{resource_plural}") \
+              do |id, params = {}, opts = {}|
+                url = send(resource_url_method, id)
+                resp, opts = execute_resource_request(:get, url, params, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
+          else
+            raise ArgumentError, "Unknown operation: #{operation.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stripe/api_operations/request.rb

@@ -1,28 +1,81 @@
+# frozen_string_literal: true
+
 module Stripe
   module APIOperations
     module Request
       module ClassMethods
-        OPTS_KEYS_TO_PERSIST = Set[:api_key, :api_base, :stripe_account, :stripe_version]
+        def execute_resource_request(method, url,
+                                     params = {}, opts = {})
+          params ||= {}
+
+          error_on_invalid_params(params)
+          warn_on_opts_in_params(params)
 
-        def request(method, url, params={}, opts={})
           opts = Util.normalize_opts(opts)
+          error_on_non_string_user_opts(opts)
+
+          opts[:client] ||= StripeClient.active_client
 
           headers = opts.clone
           api_key = headers.delete(:api_key)
           api_base = headers.delete(:api_base)
+          client = headers.delete(:client)
           # Assume all remaining opts must be headers
 
-          response, opts[:api_key] = Stripe.request(method, url, api_key, params, headers, api_base)
+          resp, opts[:api_key] = client.execute_request(
+            method, url,
+            api_base: api_base, api_key: api_key,
+            headers: headers, params: params
+          )
 
           # Hash#select returns an array before 1.9
           opts_to_persist = {}
           opts.each do |k, v|
-            if OPTS_KEYS_TO_PERSIST.include?(k)
-              opts_to_persist[k] = v
-            end
+            opts_to_persist[k] = v if Util::OPTS_PERSISTABLE.include?(k)
           end
 
-          [response, opts_to_persist]
+          [resp, opts_to_persist]
+        end
+
+        # 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
+        # something more unique.
+        #
+        # The former name had been around for just about forever though, and
+        # although all internal uses have been renamed, I've left this alias in
+        # place for backwards compatibility. Consider removing it on the next
+        # major.
+        alias request execute_resource_request
+
+        private def error_on_non_string_user_opts(opts)
+          Util::OPTS_USER_SPECIFIED.each do |opt|
+            next unless opts.key?(opt)
+
+            val = opts[opt]
+            next if val.nil?
+            next if val.is_a?(String)
+
+            raise ArgumentError,
+                  "request option '#{opt}' should be a string value " \
+                    "(was a #{val.class})"
+          end
+        end
+
+        private def error_on_invalid_params(params)
+          return if params.nil? || params.is_a?(Hash)
+
+          raise ArgumentError,
+                "request params should be either a Hash or nil " \
+                  "(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
+          end
         end
       end
 
@@ -30,12 +83,14 @@ module Stripe
         base.extend(ClassMethods)
       end
 
-      protected
-
-      def request(method, url, params={}, opts={})
+      protected def execute_resource_request(method, url,
+                                             params = {}, opts = {})
         opts = @opts.merge(Util.normalize_opts(opts))
-        self.class.request(method, url, params, opts)
+        self.class.execute_resource_request(method, url, params, opts)
       end
+
+      # See notes on `alias` above.
+      alias request execute_resource_request
     end
   end
 end

data/lib/stripe/api_operations/save.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Stripe
+  module APIOperations
+    module Save
+      module ClassMethods
+        # Updates an API resource
+        #
+        # Updates the identified resource with the passed in parameters.
+        #
+        # ==== Attributes
+        #
+        # * +id+ - ID of the resource to update.
+        # * +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(id, params = {}, opts = {})
+          params.each_key do |k|
+            if protected_fields.include?(k)
+              raise ArgumentError, "Cannot update protected field: #{k}"
+            end
+          end
+
+          resp, opts = execute_resource_request(:post, "#{resource_url}/#{id}",
+                                                params, opts)
+          Util.convert_to_stripe_object(resp.data, opts)
+        end
+      end
+
+      # Creates or updates an 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)
+
+        # 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)
+      end
+
+      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
+
+      private def save_url
+        # This switch essentially allows us "upsert"-like functionality. If the
+        # API resource doesn't have an ID set (suggesting that it's new) and
+        # its class responds to .create (which comes from
+        # Stripe::APIOperations::Create), then use the URL to create a new
+        # resource. Otherwise, generate a URL based on the object's identifier
+        # for a normal update.
+        if self[:id].nil? && self.class.respond_to?(:create)
+          self.class.resource_url
+        else
+          resource_url
+        end
+      end
+    end
+  end
+end

data/lib/stripe/api_resource.rb

@@ -1,35 +1,119 @@
+# frozen_string_literal: true
+
 module Stripe
   class APIResource < StripeObject
     include Stripe::APIOperations::Request
 
+    # A flag that can be set a behavior that will cause this resource to be
+    # encoded and sent up along with an update of its parent resource. This is
+    # usually not desirable because resources are updated individually on their
+    # own endpoints, but there are certain cases, replacing a customer's source
+    # for example, where this is allowed.
+    attr_accessor :save_with_parent
+
     def self.class_name
-      self.name.split('::')[-1]
+      name.split("::")[-1]
     end
 
-    def self.url
+    def self.resource_url
       if self == APIResource
-        raise NotImplementedError.new('APIResource is an abstract class.  You should perform actions on its subclasses (Charge, Customer, etc.)')
+        raise NotImplementedError,
+              "APIResource is an abstract class. You should perform actions " \
+              "on its subclasses (Charge, Customer, etc.)"
       end
-      "/v1/#{CGI.escape(class_name.downcase)}s"
+      # 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"
     end
 
-    def url
-      unless id = self['id']
-        raise InvalidRequestError.new("Could not determine which URL to request: #{self.class} instance has invalid ID: #{id.inspect}", 'id')
+    # A metaprogramming call that specifies that a field of a resource can be
+    # its own type of API resource (say a nested card under an account for
+    # example), and if that resource is set, it should be transmitted to the
+    # API on a create or update. Doing so is not the default behavior because
+    # API resources should normally be persisted on their own RESTful
+    # endpoints.
+    def self.save_nested_resource(name)
+      define_method(:"#{name}=") do |value|
+        super(value)
+
+        # The parent setter will perform certain useful operations like
+        # converting to an APIResource if appropriate. Refresh our argument
+        # value to whatever it mutated to.
+        value = send(name)
+
+        # Note that the value may be subresource, but could also be a scalar
+        # (like a tokenized card's ID for example), so we check the type before
+        # setting #save_with_parent here.
+        value.save_with_parent = true if value.is_a?(APIResource)
+
+        value
       end
-      "#{self.class.url}/#{CGI.escape(id)}"
+    end
+
+    # Adds a custom method to a resource class. This is used to add support for
+    # non-CRUDL API requests, e.g. capturing charges. custom_method takes the
+    # following parameters:
+    # - name: the name of the custom method to create (as a symbol)
+    # - http_verb: the HTTP verb for the API request (:get, :post, or :delete)
+    # - http_path: the path to append to the resource's URL. If not provided,
+    #              the name is used as the path
+    #
+    # For example, this call:
+    #     custom_method :capture, http_verb: post
+    # 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)
+      unless %i[get post delete].include?(http_verb)
+        raise ArgumentError,
+              "Invalid http_verb value: #{http_verb.inspect}. Should be one " \
+              "of :get, :post or :delete."
+      end
+      http_path ||= name.to_s
+      define_singleton_method(name) do |id, params = {}, opts = {}|
+        unless id.is_a?(String)
+          raise ArgumentError,
+                "id should be a string representing the ID of an API resource"
+        end
+
+        url = "#{resource_url}/#{CGI.escape(id)}/#{CGI.escape(http_path)}"
+        resp, opts = execute_resource_request(http_verb, url, params, opts)
+        Util.convert_to_stripe_object(resp.data, opts)
+      end
+    end
+
+    def resource_url
+      unless (id = self["id"])
+        raise InvalidRequestError.new(
+          "Could not determine which URL to request: #{self.class} instance " \
+          "has invalid ID: #{id.inspect}",
+          "id"
+        )
+      end
+      "#{self.class.resource_url}/#{CGI.escape(id)}"
     end
 
     def refresh
-      response, opts = request(:get, url, @retrieve_params)
-      refresh_from(response, opts)
+      resp, opts = execute_resource_request(:get, resource_url,
+                                            @retrieve_params)
+      initialize_from(resp.data, opts)
     end
 
-    def self.retrieve(id, opts={})
+    def self.retrieve(id, opts = {})
       opts = Util.normalize_opts(opts)
-      instance = self.new(id, opts)
+      instance = new(id, opts)
       instance.refresh
       instance
     end
+
+    protected def request_stripe_object(method:, path:, params:, opts: {})
+      resp, opts = execute_resource_request(method, path, params, opts)
+
+      # 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)
+      else
+        Util.convert_to_stripe_object(resp.data, opts)
+      end
+    end
   end
 end