stripe 2.0.3 → 5.55.0

data/lib/stripe/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Stripe
   # StripeError is the base error from which all other more specific Stripe
   # errors derive.
@@ -8,8 +10,8 @@ module Stripe
     # about the response that conveyed the error.
     attr_accessor :response
 
-    # These fields are now available as part of #response and that usage should
-    # be preferred.
+    attr_reader :code
+    attr_reader :error
     attr_reader :http_body
     attr_reader :http_headers
     attr_reader :http_status
@@ -17,14 +19,30 @@ 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)
+    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
       @http_headers = http_headers || {}
+      @idempotent_replayed = @http_headers["idempotent-replayed"] == "true"
       @json_body = json_body
-      @request_id = @http_headers[:request_id]
+      @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
+
+    # Whether the error was the result of an idempotent replay, meaning that it
+    # originally occurred on a previous request and is being replayed back
+    # because the user sent the same idempotency key for this one.
+    def idempotent_replayed?
+      @idempotent_replayed
     end
 
     def to_s
@@ -55,26 +73,32 @@ module Stripe
   # CardError is raised when a user enters a card that can't be charged for
   # some reason.
   class CardError < StripeError
-    attr_reader :param, :code
+    attr_reader :param
 
-    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)
+                     json_body: json_body, http_headers: http_headers,
+                     code: code)
       @param = param
-      @code = code
     end
   end
 
+  # IdempotencyError is raised in cases where an idempotency key was used
+  # improperly.
+  class IdempotencyError < StripeError
+  end
+
   # InvalidRequestError is raised when a request is initiated with invalid
   # parameters.
   class InvalidRequestError < StripeError
     attr_accessor :param
 
-    def initialize(message, param, http_status: nil, http_body: nil, json_body: nil,
-                   http_headers: 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)
+                     json_body: json_body, http_headers: http_headers,
+                     code: code)
       @param = param
     end
   end
@@ -89,4 +113,65 @@ module Stripe
   # back off on request rate.
   class RateLimitError < StripeError
   end
+
+  # SignatureVerificationError is raised when the signature verification for a
+  # webhook fails
+  class SignatureVerificationError < StripeError
+    attr_accessor :sig_header
+
+    def initialize(message, sig_header, http_body: nil)
+      super(message, http_body: http_body)
+      @sig_header = sig_header
+    end
+  end
+
+  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)
+        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
+    # the API key mode (live or test) doesn't match the client mode. Or the
+    # stripe_user_id doesn't exist or isn't connected to your application.
+    class InvalidClientError < OAuthError
+    end
+
+    # InvalidGrantError is raised when a specified code doesn't exist, is
+    # expired, has been used, or doesn't belong to you; a refresh token doesn't
+    # exist, or doesn't belong to you; or if an API key's mode (live or test)
+    # doesn't match the mode of a code or refresh token.
+    class InvalidGrantError < OAuthError
+    end
+
+    # InvalidRequestError is raised when a code, refresh token, or grant type
+    # parameter is not provided, but was required.
+    class InvalidRequestError < OAuthError
+    end
+
+    # InvalidScopeError is raised when an invalid scope parameter is provided.
+    class InvalidScopeError < OAuthError
+    end
+
+    # UnsupportedGrantTypeError is raised when an unuspported grant type
+    # parameter is specified.
+    class UnsupportedGrantTypeError < OAuthError
+    end
+
+    # UnsupportedResponseTypeError is raised when an unsupported response type
+    # parameter is specified.
+    class UnsupportedResponseTypeError < OAuthError
+    end
+  end
 end

data/lib/stripe/instrumentation.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Stripe
+  class Instrumentation
+    # Event emitted on `request_begin` callback.
+    class RequestBeginEvent
+      attr_reader :method
+      attr_reader :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`.
+      # `request_begin` subscribers can set keys which will then be available
+      # in `request_end`.
+      #
+      # Note that all subscribers of `request_begin` share the same object, so
+      # they must be careful to set unique keys so as to not conflict with data
+      # set by other subscribers.
+      attr_reader :user_data
+
+      def initialize(method:, path:, user_data:)
+        @method = method
+        @path = path
+        @user_data = user_data
+        freeze
+      end
+    end
+
+    # 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
+
+      # Arbitrary user-provided data in the form of a Ruby hash that's passed
+      # from subscribers on `request_begin` to subscribers on `request_end`.
+      # `request_begin` subscribers can set keys which will then be available
+      # in `request_end`.
+      attr_reader :user_data
+
+      def initialize(duration:, http_status:, method:, num_retries:, path:,
+                     request_id:, user_data: nil)
+        @duration = duration
+        @http_status = http_status
+        @method = method
+        @num_retries = num_retries
+        @path = path
+        @request_id = request_id
+        @user_data = user_data
+        freeze
+      end
+    end
+
+    # This class was renamed for consistency. This alias is here for backwards
+    # compatibility.
+    RequestEvent = RequestEndEvent
+
+    # Returns true if there are a non-zero number of subscribers on the given
+    # topic, and false otherwise.
+    def self.any_subscribers?(topic)
+      !subscribers[topic].empty?
+    end
+
+    def self.subscribe(topic, name = rand, &block)
+      subscribers[topic][name] = block
+      name
+    end
+
+    def self.unsubscribe(topic, name)
+      subscribers[topic].delete(name)
+    end
+
+    def self.notify(topic, event)
+      subscribers[topic].each_value { |subscriber| subscriber.call(event) }
+    end
+
+    def self.subscribers
+      @subscribers ||= Hash.new { |hash, key| hash[key] = {} }
+    end
+    private_class_method :subscribers
+  end
+end

data/lib/stripe/list_object.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Stripe
   class ListObject < StripeObject
     include Enumerable
@@ -5,6 +7,8 @@ module Stripe
     include Stripe::APIOperations::Request
     include Stripe::APIOperations::Create
 
+    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,
     # expansions, and predicates as a user pages through resources.
@@ -13,8 +17,8 @@ module Stripe
     # An empty list object. This is returned from +next+ when we know that
     # there isn't a next page in order to replicate the behavior of the API
     # when it attempts to return a page beyond the last.
-    def self.empty_list(opts={})
-      ListObject.construct_from({ :data => [] }, opts)
+    def self.empty_list(opts = {})
+      ListObject.construct_from({ data: [] }, opts)
     end
 
     def initialize(*args)
@@ -22,12 +26,16 @@ module Stripe
       self.filters = {}
     end
 
-    def [](k)
-      case k
+    def [](key)
+      case key
       when String, Symbol
         super
       else
-        raise ArgumentError.new("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
 
@@ -37,12 +45,22 @@ module Stripe
     # Note that this method makes no effort to fetch a new page when it gets to
     # the end of the current page's resources. See also +auto_paging_each+.
     def each(&blk)
-      self.data.each(&blk)
+      data.each(&blk)
     end
 
     # Iterates through each resource in all pages, making additional fetches to
     # the API as necessary.
     #
+    # The default iteration direction is forwards according to Stripe's API
+    # "natural" ordering direction -- newer objects first, and moving towards
+    # older objects.
+    #
+    # However, if the initial list object was fetched using an `ending_before`
+    # cursor (and only `ending_before`, `starting_after` cannot also be
+    # included), the method assumes that the user is trying to iterate
+    # backwards compared to natural ordering and returns results that way --
+    # older objects first, and moving towards newer objects.
+    #
     # Note that this method will make as many API calls as necessary to fetch
     # all resources. For more granular control, please see +each+ and
     # +next_page+.
@@ -51,20 +69,31 @@ module Stripe
 
       page = self
       loop do
-        page.each(&blk)
-        page = page.next_page
+        # Backward iterating activates if we have an `ending_before` constraint
+        # and _just_ an `ending_before` constraint. If `starting_after` was
+        # also used, we iterate forwards normally.
+        if filters.include?(:ending_before) &&
+           !filters.include?(:starting_after)
+          page.reverse_each(&blk)
+          page = page.previous_page
+        else
+          page.each(&blk)
+          page = page.next_page
+        end
+
         break if page.empty?
       end
     end
 
     # Returns true if the page object contains no elements.
     def empty?
-      self.data.empty?
+      data.empty?
     end
 
-    def retrieve(id, opts={})
+    def retrieve(id, opts = {})
       id, retrieve_params = Util.normalize_id(id)
-      resp, opts = request(:get,"#{resource_url}/#{CGI.escape(id)}", retrieve_params, opts)
+      url = "#{resource_url}/#{CGI.escape(id)}"
+      resp, opts = execute_resource_request(:get, url, retrieve_params, opts)
       Util.convert_to_stripe_object(resp.data, opts)
     end
 
@@ -72,13 +101,12 @@ module Stripe
     #
     # This method will try to respect the limit of the current page. If none
     # was given, the default limit will be fetched again.
-    def next_page(params={}, opts={})
-      return self.class.empty_list(opts) if !has_more
+    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)
+      params = filters.merge(starting_after: last_id).merge(params)
 
       list(params, opts)
     end
@@ -87,19 +115,25 @@ module Stripe
     #
     # This method will try to respect the limit of the current page. If none
     # was given, the default limit will be fetched again.
-    def previous_page(params={}, opts={})
+    def previous_page(params = {}, opts = {})
+      return self.class.empty_list(opts) unless has_more
+
       first_id = data.first.id
 
-      params = filters.merge({
-        :ending_before => first_id,
-      }).merge(params)
+      params = filters.merge(ending_before: first_id).merge(params)
 
       list(params, opts)
     end
 
     def resource_url
-      self.url ||
+      url ||
         raise(ArgumentError, "List object does not contain a 'url' field.")
     end
+
+    # Iterates through each resource in the page represented by the current
+    # `ListObject` in reverse.
+    def reverse_each(&blk)
+      data.reverse_each(&blk)
+    end
   end
 end

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

data/lib/stripe/oauth.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Stripe
+  module OAuth
+    module OAuthOperations
+      extend APIOperations::Request::ClassMethods
+
+      def self.execute_resource_request(method, url, params, opts)
+        opts = Util.normalize_opts(opts)
+        opts[:client] ||= opts[:client] || StripeClient.active_client
+        opts[:api_base] ||= opts[:client].config.connect_base
+
+        super(method, url, params, opts)
+      end
+    end
+
+    def self.get_client_id(params = {})
+      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."
+      end
+      client_id
+    end
+
+    def self.authorize_url(params = {}, opts = {})
+      client = opts[:client] || StripeClient.active_client
+      base = opts[:connect_base] || client.config.connect_base
+
+      path = "/oauth/authorize"
+      path = "/express" + path if opts[:express]
+
+      params[:client_id] = get_client_id(params)
+      params[:response_type] ||= "code"
+      query = Util.encode_parameters(params)
+
+      "#{base}#{path}?#{query}"
+    end
+
+    def self.token(params = {}, opts = {})
+      opts = Util.normalize_opts(opts)
+      opts[:api_key] = params[:client_secret] if params[:client_secret]
+      resp, opts = OAuthOperations.execute_resource_request(
+        :post, "/oauth/token", params, opts
+      )
+      # This is just going to return a generic StripeObject, but that's okay
+      Util.convert_to_stripe_object(resp.data, opts)
+    end
+
+    def self.deauthorize(params = {}, opts = {})
+      opts = Util.normalize_opts(opts)
+      params[:client_id] = get_client_id(params)
+      resp, opts = OAuthOperations.execute_resource_request(
+        :post, "/oauth/deauthorize", params, opts
+      )
+      # This is just going to return a generic StripeObject, but that's okay
+      Util.convert_to_stripe_object(resp.data, opts)
+    end
+  end
+end