stripe 1.31.0 → 1.58.0

data/lib/stripe/errors.rb

@@ -0,0 +1,82 @@
+module Stripe
+  # StripeError is the base error from which all other more specific Stripe
+  # errors derive.
+  class StripeError < StandardError
+    attr_reader :message
+    attr_reader :http_status
+    attr_reader :http_body
+    attr_reader :http_headers
+    attr_reader :request_id
+    attr_reader :json_body
+
+    def initialize(message=nil, http_status=nil, http_body=nil, json_body=nil,
+                   http_headers=nil)
+      @message = message
+      @http_status = http_status
+      @http_body = http_body
+      @http_headers = http_headers || {}
+      @json_body = json_body
+      @request_id = @http_headers[:request_id]
+    end
+
+    def to_s
+      status_string = @http_status.nil? ? "" : "(Status #{@http_status}) "
+      id_string = @request_id.nil? ? "" : "(Request #{@request_id}) "
+      "#{status_string}#{id_string}#{@message}"
+    end
+  end
+
+  # AuthenticationError is raised when invalid credentials are used to connect
+  # to Stripe's servers.
+  class AuthenticationError < StripeError
+  end
+
+  # APIConnectionError is raised in the event that the SDK can't connect to
+  # Stripe's servers. That can be for a variety of different reasons from a
+  # downed network to a bad TLS certificate.
+  class APIConnectionError < StripeError
+  end
+
+  # APIError is a generic error that may be raised in cases where none of the
+  # other named errors cover the problem. It could also be raised in the case
+  # that a new error has been introduced in the API, but this version of the
+  # Ruby SDK doesn't know how to handle it.
+  class APIError < StripeError
+  end
+
+  # CardError is raised when a user enters a card that can't be charged for
+  # some reason.
+  class CardError < StripeError
+    attr_reader :param, :code
+
+    def initialize(message, param, code, http_status=nil, http_body=nil, json_body=nil,
+                   http_headers=nil)
+      super(message, http_status, http_body, json_body, http_headers)
+      @param = param
+      @code = code
+    end
+  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)
+      super(message, http_status, http_body, json_body, http_headers)
+      @param = param
+    end
+  end
+
+  # PermissionError is raised in cases where access was attempted on a resource
+  # that wasn't allowed.
+  class PermissionError < StripeError
+  end
+
+  # RateLimitError is raised in cases where an account is putting too much load
+  # on Stripe's API servers (usually by performing too many requests). Please
+  # back off on request rate.
+  class RateLimitError < StripeError
+  end
+end

data/lib/stripe/file_upload.rb

@@ -3,7 +3,7 @@ module Stripe
     extend Stripe::APIOperations::Create
     extend Stripe::APIOperations::List
 
-    def self.url
+    def self.resource_url
       "/v1/files"
     end
 

data/lib/stripe/invoice.rb

@@ -1,7 +1,7 @@
 module Stripe
   class Invoice < APIResource
     extend Stripe::APIOperations::List
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
     extend Stripe::APIOperations::Create
 
     def self.upcoming(params, opts={})
@@ -17,11 +17,11 @@ module Stripe
     private
 
     def self.upcoming_url
-      url + '/upcoming'
+      resource_url + '/upcoming'
     end
 
     def pay_url
-      url + '/pay'
+      resource_url + '/pay'
     end
   end
 end

data/lib/stripe/invoice_item.rb

@@ -3,6 +3,6 @@ module Stripe
     extend Stripe::APIOperations::List
     extend Stripe::APIOperations::Create
     include Stripe::APIOperations::Delete
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
   end
 end

data/lib/stripe/list_object.rb

@@ -3,6 +3,7 @@ module Stripe
     include Enumerable
     include Stripe::APIOperations::List
     include Stripe::APIOperations::Request
+    include Stripe::APIOperations::Create
 
     # This accessor allows a `ListObject` to inherit various filters that were
     # given to a predecessor. This allows for things like consistent limits,
@@ -63,12 +64,7 @@ module Stripe
 
     def retrieve(id, opts={})
       id, retrieve_params = Util.normalize_id(id)
-      response, opts = request(:get,"#{url}/#{CGI.escape(id)}", retrieve_params, opts)
-      Util.convert_to_stripe_object(response, opts)
-    end
-
-    def create(params={}, opts={})
-      response, opts = request(:post, url, params, opts)
+      response, opts = request(:get,"#{resource_url}/#{CGI.escape(id)}", retrieve_params, opts)
       Util.convert_to_stripe_object(response, opts)
     end
 
@@ -100,5 +96,10 @@ module Stripe
 
       list(params, opts)
     end
+
+    def resource_url
+      self.url ||
+        raise(ArgumentError, "List object does not contain a 'url' field.")
+    end
   end
 end

data/lib/stripe/order.rb

@@ -2,18 +2,26 @@ module Stripe
   class Order < APIResource
     extend Stripe::APIOperations::List
     extend Stripe::APIOperations::Create
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
 
     def pay(params, opts={})
       response, opts = request(:post, pay_url, params, opts)
       initialize_from(response, opts)
     end
 
+    def return_order(params, opts={})
+      response, opts = request(:post, returns_url, params, opts)
+      Util.convert_to_stripe_object(response, opts)
+    end
+
     private
 
     def pay_url
-      url + "/pay"
+      resource_url + '/pay'
     end
 
+    def returns_url
+      resource_url + '/returns'
+    end
   end
 end

data/lib/stripe/order_return.rb

@@ -0,0 +1,9 @@
+module Stripe
+  class OrderReturn < APIResource
+    extend Stripe::APIOperations::List
+
+    def self.resource_url
+      "/v1/order_returns"
+    end
+  end
+end

data/lib/stripe/plan.rb

@@ -3,6 +3,6 @@ module Stripe
     extend Stripe::APIOperations::Create
     include Stripe::APIOperations::Delete
     extend Stripe::APIOperations::List
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
   end
 end

data/lib/stripe/product.rb

@@ -2,15 +2,7 @@ module Stripe
   class Product < APIResource
     extend Stripe::APIOperations::List
     extend Stripe::APIOperations::Create
-    include Stripe::APIOperations::Update
-
-    # Keep APIResource#url as `api_url` to avoid letting the external URL
-    # replace the Stripe URL.
-    alias_method :api_url, :url
-
-    # Override Stripe::APIOperations::Update#save to explicitly pass URL.
-    def save
-      super(:req_url => api_url)
-    end
+    include Stripe::APIOperations::Save
+    include Stripe::APIOperations::Delete
   end
 end

data/lib/stripe/recipient.rb

@@ -2,7 +2,7 @@ module Stripe
   class Recipient < APIResource
     extend Stripe::APIOperations::Create
     include Stripe::APIOperations::Delete
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
     extend Stripe::APIOperations::List
 
     def transfers

data/lib/stripe/refund.rb

@@ -2,6 +2,6 @@ module Stripe
   class Refund < APIResource
     extend Stripe::APIOperations::Create
     extend Stripe::APIOperations::List
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
   end
 end

data/lib/stripe/reversal.rb

@@ -1,10 +1,14 @@
 module Stripe
   class Reversal < APIResource
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
     extend Stripe::APIOperations::List
 
-    def url
-      "#{Transfer.url}/#{CGI.escape(transfer)}/reversals/#{CGI.escape(id)}"
+    def resource_url
+      "#{Transfer.resource_url}/#{CGI.escape(transfer)}/reversals/#{CGI.escape(id)}"
+    end
+
+    def self.update(id, params=nil, opts=nil)
+      raise NotImplementedError.new("Reversals cannot be updated without a transfer ID. Update a reversal using `r = transfer.reversals.retrieve('reversal_id'); r.save`")
     end
 
     def self.retrieve(id, opts={})

data/lib/stripe/singleton_api_resource.rb

@@ -1,14 +1,14 @@
 module Stripe
   class SingletonAPIResource < APIResource
-    def self.url
+    def self.resource_url
       if self == SingletonAPIResource
         raise NotImplementedError.new('SingletonAPIResource is an abstract class.  You should perform actions on its subclasses (Account, etc.)')
       end
       "/v1/#{CGI.escape(class_name.downcase)}"
     end
 
-    def url
-      self.class.url
+    def resource_url
+      self.class.resource_url
     end
 
     def self.retrieve(opts={})

data/lib/stripe/sku.rb

@@ -2,7 +2,7 @@ module Stripe
   class SKU < APIResource
     extend Stripe::APIOperations::List
     extend Stripe::APIOperations::Create
-    include Stripe::APIOperations::Update
-
+    include Stripe::APIOperations::Save
+    include Stripe::APIOperations::Delete
   end
 end

data/lib/stripe/source.rb

@@ -0,0 +1,11 @@
+module Stripe
+  class Source < APIResource
+    extend Stripe::APIOperations::Create
+    include Stripe::APIOperations::Save
+
+    def verify(params={}, opts={})
+      response, opts = request(:post, resource_url + '/verify', params, opts)
+      initialize_from(response, opts)
+    end
+  end
+end

data/lib/stripe/stripe_object.rb

@@ -12,6 +12,7 @@ module Stripe
     def initialize(id=nil, opts={})
       id, @retrieve_params = Util.normalize_id(id)
       @opts = Util.normalize_opts(opts)
+      @original_values = {}
       @values = {}
       # This really belongs in APIResource, but not putting it there allows us
       # to have a unified inspect method
@@ -31,7 +32,7 @@ module Stripe
     # considered to be equal if they have the same set of values and each one
     # of those values is the same.
     def ==(other)
-      @values == other.instance_variable_get(:@values)
+      other.is_a?(StripeObject) && @values == other.instance_variable_get(:@values)
     end
 
     # Indicates whether or not the resource has been deleted on the server.
@@ -42,7 +43,7 @@ module Stripe
     end
 
     def to_s(*args)
-      JSON.pretty_generate(@values)
+      JSON.pretty_generate(to_hash)
     end
 
     def inspect
@@ -71,13 +72,22 @@ module Stripe
     #
     # * +values+ - Hash of values to use to update the current attributes of
     #   the object.
+    # * +opts+ - Options for +StripeObject+ like an API key that will be reused
+    #   on subsequent API calls.
     #
     # ==== Options
     #
-    # * +:opts+ Options for StripeObject like an API key.
-    def update_attributes(values, opts = {})
+    # * +:dirty+ - Whether values should be initiated as "dirty" (unsaved) and
+    #   which applies only to new StripeObjects being initiated under this
+    #   StripeObject. Defaults to true.
+    def update_attributes(values, opts = {}, method_options = {})
+      # Default to true. TODO: Convert to optional arguments after we're off
+      # 1.9 which will make this quite a bit more clear.
+      dirty = method_options.fetch(:dirty, true)
       values.each do |k, v|
+        add_accessors([k], values) unless metaclass.method_defined?(k.to_sym)
         @values[k] = Util.convert_to_stripe_object(v, opts)
+        dirty_value!(@values[k]) if dirty
         @unsaved_values.add(k)
       end
     end
@@ -135,125 +145,109 @@ module Stripe
       construct_from(values, opts)
     end
 
-    if RUBY_VERSION < '1.9.2'
-      def respond_to?(symbol)
-        @values.has_key?(symbol) || super
+    # Sets all keys within the StripeObject as unsaved so that they will be
+    # included with an update when #serialize_params is called. This method is
+    # also recursive, so any StripeObjects contained as values or which are
+    # values in a tenant array are also marked as dirty.
+    def dirty!
+      @unsaved_values = Set.new(@values.keys)
+      @values.each do |k, v|
+        dirty_value!(v)
       end
     end
 
-    def serialize_nested_object(key)
-      new_value = @values[key]
-      if new_value.is_a?(APIResource)
-        return {}
-      end
-
-      if @unsaved_values.include?(key)
-        # the object has been reassigned
-        # e.g. as object.key = {foo => bar}
-        update = new_value
-        new_keys = update.keys.map(&:to_sym)
-
-        # remove keys at the server, but not known locally
-        if @original_values[key]
-          keys_to_unset = @original_values[key].keys - new_keys
-          keys_to_unset.each {|key| update[key] = ''}
+    def serialize_params(options = {})
+      update_hash = {}
+
+      @values.each do |k, v|
+        # There are a few reasons that we may want to add in a parameter for
+        # update:
+        #
+        #   1. The `force` option has been set.
+        #   2. We know that it was modified.
+        #   3. Its value is a StripeObject. A StripeObject may contain modified
+        #      values within in that its parent StripeObject doesn't know about.
+        #
+        unsaved = @unsaved_values.include?(k)
+        if options[:force] || unsaved || v.is_a?(StripeObject)
+          update_hash[k.to_sym] =
+            serialize_params_value(@values[k], @original_values[k], unsaved, options[:force])
         end
-
-        update
-      else
-        # can be serialized normally
-        self.class.serialize_params(new_value)
       end
-    end
-
-    def self.serialize_params(obj, original_value=nil)
-      case obj
-      when nil
-        ''
-      when Array
-        update = obj.map { |v| serialize_params(v) }
-        if original_value != update
-          update
-        else
-          nil
-        end
-      when StripeObject
-        unsaved_keys = obj.instance_variable_get(:@unsaved_values)
-        obj_values = obj.instance_variable_get(:@values)
-        update_hash = {}
 
-        unsaved_keys.each do |k|
-          update_hash[k] = serialize_params(obj_values[k])
-        end
+      # a `nil` that makes it out of `#serialize_params_value` signals an empty
+      # value that we shouldn't appear in the serialized form of the object
+      update_hash.reject! { |_, v| v == nil }
 
-        obj_values.each do |k, v|
-           if v.is_a?(Array)
-             original_value = obj.instance_variable_get(:@original_values)[k]
-
-             # the conditional here tests whether the old and new values are
-             # different (and therefore needs an update), or the same (meaning
-             # we can leave it out of the request)
-             if updated = serialize_params(v, original_value)
-               update_hash[k] = updated
-             else
-               update_hash.delete(k)
-             end
-          elsif v.is_a?(StripeObject) || v.is_a?(Hash)
-             update_hash[k] = obj.serialize_nested_object(k)
-          end
-        end
+      update_hash
+    end
 
-        update_hash
-      else
-        obj
+    class << self
+      # This class method has been deprecated in favor of the instance method
+      # of the same name.
+      def serialize_params(obj, options = {})
+        obj.serialize_params(options)
       end
+      extend Gem::Deprecate
+      deprecate :serialize_params, "#serialize_params", 2016, 9
     end
 
     protected
 
-    def metaclass
-      class << self; self; end
+    # A protected field is one that doesn't get an accessor assigned to it
+    # (i.e. `obj.public = ...`) and one which is not allowed to be updated via
+    # the class level `Model.update(id, { ... })`.
+    def self.protected_fields
+      []
     end
 
-    def protected_fields
-      []
+    def metaclass
+      class << self; self; end
     end
 
     def remove_accessors(keys)
-      f = protected_fields
+      # not available in the #instance_eval below
+      protected_fields = self.class.protected_fields
+
       metaclass.instance_eval do
         keys.each do |k|
-          next if f.include?(k)
+          next if protected_fields.include?(k)
           next if @@permanent_attributes.include?(k)
-          k_eq = :"#{k}="
-          remove_method(k) if method_defined?(k)
-          remove_method(k_eq) if method_defined?(k_eq)
+
+          # Remove methods for the accessor's reader and writer.
+          [k, :"#{k}=", :"#{k}?"].each do |method_name|
+            if method_defined?(method_name)
+              remove_method(method_name)
+            end
+          end
         end
       end
     end
 
     def add_accessors(keys, values)
-      f = protected_fields
+      # not available in the #instance_eval below
+      protected_fields = self.class.protected_fields
+
       metaclass.instance_eval do
         keys.each do |k|
-          next if f.include?(k)
+          next if protected_fields.include?(k)
           next if @@permanent_attributes.include?(k)
-          k_eq = :"#{k}="
+
           define_method(k) { @values[k] }
-          define_method(k_eq) do |v|
+          define_method(:"#{k}=") do |v|
             if v == ""
               raise ArgumentError.new(
-                "You cannot set #{k} to an empty string." \
-                "We interpret empty strings as nil in requests." \
-                "You may set #{self}.#{k} = nil to delete the property.")
+                "You cannot set #{k} to an empty string. " \
+                "We interpret empty strings as nil in requests. " \
+                "You may set (object).#{k} = nil to delete the property.")
             end
-            @values[k] = v
+            @values[k] = Util.convert_to_stripe_object(v, @opts)
+            dirty_value!(@values[k])
             @unsaved_values.add(k)
           end
 
           if [FalseClass, TrueClass].include?(values[k].class)
-            k_bool = :"#{k}?"
-            define_method(k_bool) { @values[k] }
+            define_method(:"#{k}?") { @values[k] }
           end
         end
       end
@@ -315,10 +309,8 @@ module Stripe
       # customer, where there is no persistent card parameter.  Mark those values
       # which don't persist as transient
 
-      instance_eval do
-        remove_accessors(removed)
-        add_accessors(added, values)
-      end
+      remove_accessors(removed)
+      add_accessors(added, values)
 
       removed.each do |k|
         @values.delete(k)
@@ -326,7 +318,7 @@ module Stripe
         @unsaved_values.delete(k)
       end
 
-      update_attributes(values, opts)
+      update_attributes(values, opts, :dirty => false)
       values.each do |k, _|
         @transient_values.delete(k)
         @unsaved_values.delete(k)
@@ -334,5 +326,89 @@ module Stripe
 
       self
     end
+
+    def serialize_params_value(value, original, unsaved, force)
+      case true
+      when value == nil
+        ''
+
+      # The logic here is that essentially any object embedded in another
+      # object that had a `type` is actually an API resource of a different
+      # type that's been included in the response. These other resources must
+      # be updated from their proper endpoints, and therefore they are not
+      # included when serializing even if they've been modified.
+      #
+      # There are _some_ known exceptions though. For example, to save on API
+      # calls it's sometimes desirable to update a customer's default source by
+      # setting a new card (or other) object with `#source=` and then saving
+      # the customer. The `#save_with_parent` flag to override the default
+      # behavior allows us to handle these exceptions.
+      when value.is_a?(APIResource) && !value.save_with_parent
+        nil
+
+      when value.is_a?(Array)
+        update = value.map { |v| serialize_params_value(v, nil, true, force) }
+
+        # This prevents an array that's unchanged from being resent.
+        if update != serialize_params_value(original, nil, true, force)
+          update
+        else
+          nil
+        end
+
+      # Handle a Hash for now, but in the long run we should be able to
+      # eliminate all places where hashes are stored as values internally by
+      # making sure any time one is set, we convert it to a StripeObject. This
+      # will simplify our model by making data within an object more
+      # consistent.
+      #
+      # For now, you can still run into a hash if someone appends one to an
+      # existing array being held by a StripeObject. This could happen for
+      # example by appending a new hash onto `additional_owners` for an
+      # account.
+      when value.is_a?(Hash)
+        Util.convert_to_stripe_object(value, @opts).serialize_params
+
+      when value.is_a?(StripeObject)
+        update = value.serialize_params(:force => force)
+
+        # If the entire object was replaced, then we need blank each field of
+        # the old object that held a value. The new serialized values will
+        # override any of these empty values.
+        update = empty_values(original).merge(update) if original && unsaved
+
+        update
+
+      else
+        value
+      end
+    end
+
+    private
+
+    def dirty_value!(value)
+      case value
+      when Array
+        value.map { |v| dirty_value!(v) }
+      when StripeObject
+        value.dirty!
+      end
+    end
+
+    # Returns a hash of empty values for all the values that are in the given
+    # StripeObject.
+    def empty_values(obj)
+      values = case obj
+      when Hash         then obj
+      when StripeObject then obj.instance_variable_get(:@values)
+      else
+        raise ArgumentError, "#empty_values got unexpected object type: #{obj.class.name}"
+      end
+
+      values.inject({}) do |update, (k, _)|
+        update[k] = ''
+        update
+      end
+    end
   end
 end