stripe 4.10.0 → 5.0.0

data/lib/stripe/api_operations/nested_resource.rb

@@ -10,8 +10,10 @@ module Stripe
     # methods `.create_reversal`, `.retrieve_reversal`, `.update_reversal`,
     # etc. all become available.
     module NestedResource
-      def nested_resource_class_methods(resource, path: nil, operations: nil)
-        path ||= "#{resource}s"
+      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"
@@ -24,31 +26,36 @@ module Stripe
         operations.each do |operation|
           case operation
           when :create
-            define_singleton_method(:"create_#{resource}") do |id, params = {}, opts = {}|
+            define_singleton_method(:"create_#{resource}") \
+                do |id, params = {}, opts = {}|
               url = send(resource_url_method, id)
               resp, opts = 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 = {}|
+            define_singleton_method(:"retrieve_#{resource}") \
+                do |id, nested_id, opts = {}|
               url = send(resource_url_method, id, nested_id)
               resp, opts = 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 = {}|
+            define_singleton_method(:"update_#{resource}") \
+                do |id, nested_id, params = {}, opts = {}|
               url = send(resource_url_method, id, nested_id)
               resp, opts = 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 = {}|
+            define_singleton_method(:"delete_#{resource}") \
+                do |id, nested_id, params = {}, opts = {}|
               url = send(resource_url_method, id, nested_id)
               resp, opts = request(:delete, url, params, opts)
               Util.convert_to_stripe_object(resp.data, opts)
             end
           when :list
-            define_singleton_method(:"list_#{resource}s") do |id, params = {}, opts = {}|
+            define_singleton_method(:"list_#{resource_plural}") \
+                do |id, params = {}, opts = {}|
               url = send(resource_url_method, id)
               resp, opts = request(:get, url, params, opts)
               Util.convert_to_stripe_object(resp.data, opts)

data/lib/stripe/api_operations/request.rb

@@ -31,12 +31,10 @@ module Stripe
           [resp, opts_to_persist]
         end
 
-        private
-
-        def warn_on_opts_in_params(params)
+        private def warn_on_opts_in_params(params)
           Util::OPTS_USER_SPECIFIED.each do |opt|
             if params.key?(opt)
-              $stderr.puts("WARNING: #{opt} should be in opts instead of params.")
+              warn("WARNING: #{opt} should be in opts instead of params.")
             end
           end
         end
@@ -46,9 +44,7 @@ module Stripe
         base.extend(ClassMethods)
       end
 
-      protected
-
-      def request(method, url, params = {}, opts = {})
+      protected def request(method, url, params = {}, opts = {})
         opts = @opts.merge(Util.normalize_opts(opts))
         self.class.request(method, url, params, opts)
       end

data/lib/stripe/api_operations/save.rb

@@ -76,9 +76,7 @@ module Stripe
         base.extend(ClassMethods)
       end
 
-      private
-
-      def save_url
+      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

data/lib/stripe/api_resource.rb

@@ -17,7 +17,9 @@ module Stripe
 
     def self.resource_url
       if self == APIResource
-        raise NotImplementedError, "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
       # Namespaces are separated in object names with periods (.) and in URLs
       # with forward slashes (/), so replace the former with the latter.
@@ -48,9 +50,44 @@ module Stripe
       end
     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 = 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")
+        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
@@ -66,5 +103,16 @@ module Stripe
       instance.refresh
       instance
     end
+
+    protected def request_stripe_object(method:, path:, params:, opts: {})
+      resp, opts = 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

data/lib/stripe/connection_manager.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Stripe
+  # Manages connections across multiple hosts which is useful because the
+  # library may connect to multiple hosts during a typical session (main API,
+  # Connect, Uploads). Ruby doesn't provide an easy way to make this happen
+  # easily, so this class is designed to track what we're connected to and
+  # manage the lifecycle of those connections.
+  #
+  # Note that this class in itself is *not* thread safe. We expect it to be
+  # instantiated once per thread.
+  #
+  # Note also that this class doesn't currently clean up after itself because
+  # it expects to only ever have a few connections. It'd be possible to tank
+  # memory by constantly changing the value of `Stripe.api_base` or the like. A
+  # possible improvement might be to detect and prune old connections whenever
+  # a request is executed.
+  class ConnectionManager
+    def initialize
+      @active_connections = {}
+    end
+
+    # Finishes any active connections by closing their TCP connection and
+    # clears them from internal tracking.
+    def clear
+      @active_connections.each do |_, connection|
+        connection.finish
+      end
+      @active_connections = {}
+    end
+
+    # Gets a connection for a given URI. This is for internal use only as it's
+    # subject to change (we've moved between HTTP client schemes in the past
+    # and may do it again).
+    #
+    # `uri` is expected to be a string.
+    def connection_for(uri)
+      u = URI.parse(uri)
+      connection = @active_connections[[u.host, u.port]]
+
+      if connection.nil?
+        connection = create_connection(u)
+
+        # TODO: what happens after TTL?
+        connection.start
+
+        @active_connections[[u.host, u.port]] = connection
+      end
+
+      connection
+    end
+
+    # Executes an HTTP request to the given URI with the given method. Also
+    # allows a request body, headers, and query string to be specified.
+    def execute_request(method, uri, body: nil, headers: nil, query: nil)
+      # Perform some basic argument validation because it's easy to get
+      # confused between strings and hashes for things like body and query
+      # parameters.
+      raise ArgumentError, "method should be a symbol" \
+        unless method.is_a?(Symbol)
+      raise ArgumentError, "uri should be a string" \
+        unless uri.is_a?(String)
+      raise ArgumentError, "body should be a string" \
+        if body && !body.is_a?(String)
+      raise ArgumentError, "headers should be a hash" \
+        if headers && !headers.is_a?(Hash)
+      raise ArgumentError, "query should be a string" \
+        if query && !query.is_a?(String)
+
+      connection = connection_for(uri)
+
+      u = URI.parse(uri)
+      path = if query
+               u.path + "?" + query
+             else
+               u.path
+             end
+
+      connection.send_request(method.to_s.upcase, path, body, headers)
+    end
+
+    #
+    # private
+    #
+
+    # `uri` should be a parsed `URI` object.
+    private def create_connection(uri)
+      # These all come back as `nil` if no proxy is configured.
+      proxy_host, proxy_port, proxy_user, proxy_pass = proxy_parts
+
+      connection = Net::HTTP.new(uri.host, uri.port,
+                                 proxy_host, proxy_port,
+                                 proxy_user, proxy_pass)
+
+      connection.open_timeout = Stripe.open_timeout
+      connection.read_timeout = Stripe.read_timeout
+
+      connection.use_ssl = uri.scheme == "https"
+
+      if Stripe.verify_ssl_certs
+        connection.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        connection.cert_store = Stripe.ca_store
+      else
+        connection.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+        unless @verify_ssl_warned
+          @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.")
+        end
+      end
+
+      connection
+    end
+
+    # `Net::HTTP` somewhat awkwardly requires each component of a proxy URI
+    # (host, port, etc.) rather than the URI itself. This method simply parses
+    # out those pieces to make passing them into a new connection a little less
+    # ugly.
+    private def proxy_parts
+      if Stripe.proxy.nil?
+        [nil, nil, nil, nil]
+      else
+        u = URI.parse(Stripe.proxy)
+        [u.host, u.port, u.user, u.password]
+      end
+    end
+  end
+end

data/lib/stripe/error_object.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Stripe
+  # Represents an error object as returned by the API.
+  #
+  # @see https://stripe.com/docs/api/errors
+  class ErrorObject < StripeObject
+    # Unlike other objects, we explicitly declare getter methods here. This
+    # is because the API doesn't return `null` values for fields on this
+    # object, rather the fields are omitted entirely. Not declaring the getter
+    # methods would cause users to run into `NoMethodError` exceptions and
+    # get in the way of generic error handling.
+
+    # For card errors, the ID of the failed charge.
+    def charge
+      @values[:charge]
+    end
+
+    # For some errors that could be handled programmatically, a short string
+    # indicating the error code reported.
+    def code
+      @values[:code]
+    end
+
+    # For card errors resulting from a card issuer decline, a short string
+    # indicating the card issuer's reason for the decline if they provide one.
+    def decline_code
+      @values[:decline_code]
+    end
+
+    # A URL to more information about the error code reported.
+    def doc_url
+      @values[:doc_url]
+    end
+
+    # A human-readable message providing more details about the error. For card
+    # errors, these messages can be shown to your users.
+    def message
+      @values[:message]
+    end
+
+    # If the error is parameter-specific, the parameter related to the error.
+    # For example, you can use this to display a message near the correct form
+    # field.
+    def param
+      @values[:param]
+    end
+
+    # The PaymentIntent object for errors returned on a request involving a
+    # PaymentIntent.
+    def payment_intent
+      @values[:payment_intent]
+    end
+
+    # The PaymentMethod object for errors returned on a request involving a
+    # PaymentMethod.
+    def payment_method
+      @values[:payment_method]
+    end
+
+    # The SetupIntent object for errors returned on a request involving a
+    # SetupIntent.
+    def setup_intent
+      @values[:setup_intent]
+    end
+
+    # The source object for errors returned on a request involving a source.
+    def source
+      @values[:source]
+    end
+
+    # The type of error returned. One of `api_connection_error`, `api_error`,
+    # `authentication_error`, `card_error`, `idempotency_error`,
+    # `invalid_request_error`, or `rate_limit_error`.
+    def type
+      @values[:type]
+    end
+  end
+
+  # Represents on OAuth error returned by the OAuth API.
+  #
+  # @see https://stripe.com/docs/connect/oauth-reference#post-token-errors
+  class OAuthErrorObject < StripeObject
+    # A unique error code per error type.
+    def error
+      @values[:error]
+    end
+
+    # A human readable description of the error.
+    def error_description
+      @values[:error_description]
+    end
+  end
+end

data/lib/stripe/errors.rb

@@ -11,6 +11,7 @@ module Stripe
     attr_accessor :response
 
     attr_reader :code
+    attr_reader :error
     attr_reader :http_body
     attr_reader :http_headers
     attr_reader :http_status
@@ -18,8 +19,8 @@ module Stripe
     attr_reader :request_id
 
     # Initializes a StripeError.
-    def initialize(message = nil, http_status: nil, http_body: nil, json_body: nil,
-                   http_headers: nil, code: nil)
+    def initialize(message = nil, http_status: nil, http_body: nil,
+                   json_body: nil, http_headers: nil, code: nil)
       @message = message
       @http_status = http_status
       @http_body = http_body
@@ -27,6 +28,13 @@ module Stripe
       @json_body = json_body
       @code = code
       @request_id = @http_headers[:request_id]
+      @error = construct_error_object
+    end
+
+    def construct_error_object
+      return nil if @json_body.nil? || !@json_body.key?(:error)
+
+      ErrorObject.construct_from(@json_body[:error])
     end
 
     def to_s
@@ -59,9 +67,8 @@ module Stripe
   class CardError < StripeError
     attr_reader :param
 
-    # TODO: make code a keyword arg in next major release
-    def initialize(message, param, code, http_status: nil, http_body: nil, json_body: nil,
-                   http_headers: nil)
+    def initialize(message, param, code: nil, http_status: nil, http_body: nil,
+                   json_body: nil, http_headers: nil)
       super(message, http_status: http_status, http_body: http_body,
                      json_body: json_body, http_headers: http_headers,
                      code: code)
@@ -79,8 +86,8 @@ module Stripe
   class InvalidRequestError < StripeError
     attr_accessor :param
 
-    def initialize(message, param, http_status: nil, http_body: nil, json_body: nil,
-                   http_headers: nil, code: nil)
+    def initialize(message, param, http_status: nil, http_body: nil,
+                   json_body: nil, http_headers: nil, code: nil)
       super(message, http_status: http_status, http_body: http_body,
                      json_body: json_body, http_headers: http_headers,
                      code: code)
@@ -113,12 +120,18 @@ module Stripe
   module OAuth
     # OAuthError is raised when the OAuth API returns an error.
     class OAuthError < StripeError
-      def initialize(code, description, http_status: nil, http_body: nil, json_body: nil,
-                     http_headers: nil)
+      def initialize(code, description, http_status: nil, http_body: nil,
+                     json_body: nil, http_headers: nil)
         super(description, http_status: http_status, http_body: http_body,
                            json_body: json_body, http_headers: http_headers,
                            code: code)
       end
+
+      def construct_error_object
+        return nil if @json_body.nil?
+
+        OAuthErrorObject.construct_from(@json_body)
+      end
     end
 
     # InvalidClientError is raised when the client doesn't belong to you, or

data/lib/stripe/list_object.rb

@@ -7,7 +7,7 @@ module Stripe
     include Stripe::APIOperations::Request
     include Stripe::APIOperations::Create
 
-    OBJECT_NAME = "list".freeze
+    OBJECT_NAME = "list"
 
     # This accessor allows a `ListObject` to inherit various filters that were
     # given to a predecessor. This allows for things like consistent limits,
@@ -26,12 +26,16 @@ module Stripe
       self.filters = {}
     end
 
-    def [](k)
-      case k
+    def [](key)
+      case key
       when String, Symbol
         super
       else
-        raise ArgumentError, "You tried to access the #{k.inspect} index, but ListObject types only support String keys. (HINT: List calls return an object with a 'data' (which is the data array). You likely want to call #data[#{k.inspect}])"
+        raise ArgumentError,
+              "You tried to access the #{key.inspect} index, but ListObject " \
+              "types only support String keys. (HINT: List calls return an " \
+              "object with a 'data' (which is the data array). You likely " \
+              "want to call #data[#{key.inspect}])"
       end
     end
 
@@ -68,7 +72,8 @@ module Stripe
 
     def retrieve(id, opts = {})
       id, retrieve_params = Util.normalize_id(id)
-      resp, opts = request(:get, "#{resource_url}/#{CGI.escape(id)}", retrieve_params, opts)
+      resp, opts = request(:get, "#{resource_url}/#{CGI.escape(id)}",
+                           retrieve_params, opts)
       Util.convert_to_stripe_object(resp.data, opts)
     end
 
@@ -78,6 +83,7 @@ module Stripe
     # was given, the default limit will be fetched again.
     def next_page(params = {}, opts = {})
       return self.class.empty_list(opts) unless has_more
+
       last_id = data.last.id
 
       params = filters.merge(starting_after: last_id).merge(params)

data/lib/stripe/multipart_encoder.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "tempfile"
+
+module Stripe
+  # Encodes parameters into a `multipart/form-data` payload as described by RFC
+  # 2388:
+  #
+  #     https://tools.ietf.org/html/rfc2388
+  #
+  # This is most useful for transferring file-like objects.
+  #
+  # Parameters should be added with `#encode`. When ready, use `#body` to get
+  # the encoded result and `#content_type` to get the value that should be
+  # placed in the `Content-Type` header of a subsequent request (which includes
+  # a boundary value).
+  class MultipartEncoder
+    MULTIPART_FORM_DATA = "multipart/form-data"
+
+    # A shortcut for encoding a single set of parameters and finalizing a
+    # result.
+    #
+    # Returns an encoded body and the value that should be set in the content
+    # type header of a subsequent request.
+    def self.encode(params)
+      encoder = MultipartEncoder.new
+      encoder.encode(params)
+      encoder.close
+      [encoder.body, encoder.content_type]
+    end
+
+    # Gets the object's randomly generated boundary string.
+    attr_reader :boundary
+
+    # Initializes a new multipart encoder.
+    def initialize
+      # Kind of weird, but required by Rubocop because the unary plus operator
+      # is considered faster than `Stripe.new`.
+      @body = +""
+
+      # Chose the same number of random bytes that Go uses in its standard
+      # library implementation. Easily enough entropy to ensure that it won't
+      # be present in a file we're sending.
+      @boundary = SecureRandom.hex(30)
+
+      @closed = false
+      @first_field = true
+    end
+
+    # Gets the encoded body. `#close` must be called first.
+    def body
+      raise "object must be closed before getting body" unless @closed
+
+      @body
+    end
+
+    # Finalizes the object by writing the final boundary.
+    def close
+      raise "object already closed" if @closed
+
+      @body << "\r\n"
+      @body << "--#{@boundary}--"
+
+      @closed = true
+
+      nil
+    end
+
+    # Gets the value including boundary that should be put into a multipart
+    # request's `Content-Type`.
+    def content_type
+      "#{MULTIPART_FORM_DATA}; boundary=#{@boundary}"
+    end
+
+    # Encodes a set of parameters to the body.
+    #
+    # Note that parameters are expected to be a hash, but a "flat" hash such
+    # that complex substructures like hashes and arrays have already been
+    # appropriately Stripe-encoded. Pass a complex structure through
+    # `Util.flatten_params` first before handing it off to this method.
+    def encode(params)
+      raise "no more parameters can be written to closed object" if @closed
+
+      params.each do |name, val|
+        if val.is_a?(::File) || val.is_a?(::Tempfile)
+          write_field(name, val.read, filename: ::File.basename(val.path))
+        elsif val.respond_to?(:read)
+          write_field(name, val.read, filename: "blob")
+        else
+          write_field(name, val, filename: nil)
+        end
+      end
+
+      nil
+    end
+
+    #
+    # private
+    #
+
+    # Escapes double quotes so that the given value can be used in a
+    # double-quoted string and replaces any linebreak characters with spaces.
+    private def escape(str)
+      str.gsub('"', "%22").tr("\n", " ").tr("\r", " ")
+    end
+
+    private def write_field(name, data, filename:)
+      if !@first_field
+        @body << "\r\n"
+      else
+        @first_field = false
+      end
+
+      @body << "--#{@boundary}\r\n"
+
+      if filename
+        @body << %(Content-Disposition: form-data) +
+                 %(; name="#{escape(name.to_s)}") +
+                 %(; 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)
+      end
+
+      @body << "\r\n"
+      @body << data.to_s
+    end
+  end
+end