stripe 1.30.3 → 2.0.0

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

data/lib/stripe/stripe_response.rb

@@ -0,0 +1,48 @@
+module Stripe
+  # StripeResponse encapsulates some vitals of a response that came back from
+  # the Stripe API.
+  class StripeResponse
+    # The data contained by the HTTP body of the response deserialized from
+    # JSON.
+    attr_accessor :data
+
+    # The raw HTTP body of the response.
+    attr_accessor :http_body
+
+    # A Hash of the HTTP headers of the response.
+    attr_accessor :http_headers
+
+    # The integer HTTP status code of the response.
+    attr_accessor :http_status
+
+    # The Stripe request ID of the response.
+    attr_accessor :request_id
+
+    # Initializes a StripeResponse object from a Hash like the kind returned as
+    # part of a Faraday exception.
+    #
+    # This may throw JSON::ParserError if the response body is not valid JSON.
+    def self.from_faraday_hash(http_resp)
+      resp = StripeResponse.new
+      resp.data = JSON.parse(http_resp[:body], symbolize_names: true)
+      resp.http_body = http_resp[:body]
+      resp.http_headers = http_resp[:headers]
+      resp.http_status = http_resp[:status]
+      resp.request_id = http_resp[:headers]["Request-Id"]
+      resp
+    end
+
+    # Initializes a StripeResponse object from a Faraday HTTP response object.
+    #
+    # This may throw JSON::ParserError if the response body is not valid JSON.
+    def self.from_faraday_response(http_resp)
+      resp = StripeResponse.new
+      resp.data = JSON.parse(http_resp.body, symbolize_names: true)
+      resp.http_body = http_resp.body
+      resp.http_headers = http_resp.headers
+      resp.http_status = http_resp.status
+      resp.request_id = http_resp.headers["Request-Id"]
+      resp
+    end
+  end
+end

data/lib/stripe/subscription.rb

@@ -1,25 +1,31 @@
 module Stripe
   class Subscription < APIResource
-    include Stripe::APIOperations::Update
+    extend Stripe::APIOperations::List
+    extend Stripe::APIOperations::Create
+    include Stripe::APIOperations::Save
     include Stripe::APIOperations::Delete
 
-    def url
-      "#{Customer.url}/#{CGI.escape(customer)}/subscriptions/#{CGI.escape(id)}"
+    save_nested_resource :source
+
+    def delete_discount
+      _, opts = request(:delete, discount_url)
+      initialize_from({ :discount => nil }, opts, true)
     end
 
-    def self.retrieve(id, opts=nil)
-      raise NotImplementedError.new("Subscriptions cannot be retrieved without a customer ID. Retrieve a subscription using customer.subscriptions.retrieve('subscription_id')")
+    def self.update(id, params={}, opts={})
+      params[:items] = Util.array_to_hash(params[:items]) if params[:items]
+      super(id, params, opts)
     end
 
-    def delete_discount
-      response, opts = request(:delete, discount_url)
-      initialize_from({ :discount => nil }, opts, true)
+    def self.create(params={}, opts={})
+      params[:items] = Util.array_to_hash(params[:items]) if params[:items]
+      super(params, opts)
     end
 
     private
 
     def discount_url
-      url + '/discount'
+      resource_url + '/discount'
     end
   end
 end

data/lib/stripe/subscription_item.rb

@@ -0,0 +1,12 @@
+module Stripe
+  class SubscriptionItem < APIResource
+    extend Stripe::APIOperations::Create
+    include Stripe::APIOperations::Delete
+    extend Stripe::APIOperations::List
+    include Stripe::APIOperations::Save
+
+    def self.resource_url
+      '/v1/subscription_items'
+    end
+  end
+end

data/lib/stripe/three_d_secure.rb

@@ -0,0 +1,9 @@
+module Stripe
+  class ThreeDSecure < APIResource
+    extend Stripe::APIOperations::Create
+
+    def self.resource_url
+      "/v1/3d_secure"
+    end
+  end
+end

data/lib/stripe/transfer.rb

@@ -2,16 +2,15 @@ module Stripe
   class Transfer < APIResource
     extend Stripe::APIOperations::List
     extend Stripe::APIOperations::Create
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
 
     def cancel
-      response, api_key = Stripe.request(:post, cancel_url, @api_key)
-      initialize_from(response, api_key)
+      resp, api_key = self.request(:post, cancel_url)
+      initialize_from(resp.data, api_key)
     end
 
     def cancel_url
-      url + '/cancel'
+      resource_url + '/cancel'
     end
-
   end
 end

data/lib/stripe/util.rb

@@ -23,45 +23,63 @@ module Stripe
         'list' => ListObject,
 
         # business objects
-        'account' => Account,
-        'application_fee' => ApplicationFee,
-        'balance' => Balance,
-        'balance_transaction' => BalanceTransaction,
-        'bank_account' => BankAccount,
-        'card' => Card,
-        'charge' => Charge,
-        'coupon' => Coupon,
-        'customer' => Customer,
-        'event' => Event,
-        'fee_refund' => ApplicationFeeRefund,
-        'invoiceitem' => InvoiceItem,
-        'invoice' => Invoice,
-        'plan' => Plan,
-        'recipient' => Recipient,
-        'refund' => Refund,
-        'subscription' => Subscription,
-        'file_upload' => FileUpload,
-        'token' => Token,
-        'transfer' => Transfer,
-        'transfer_reversal' => Reversal,
-        'bitcoin_receiver' => BitcoinReceiver,
-        'bitcoin_transaction' => BitcoinTransaction,
-        'dispute' => Dispute,
-        'product' => Product,
-        'sku' => SKU,
-        'order' => Order,
+        'account'                 => Account,
+        'alipay_account'          => AlipayAccount,
+        'apple_pay_domain'        => ApplePayDomain,
+        'application_fee'         => ApplicationFee,
+        'balance'                 => Balance,
+        'balance_transaction'     => BalanceTransaction,
+        'bank_account'            => BankAccount,
+        'bitcoin_receiver'        => BitcoinReceiver,
+        'bitcoin_transaction'     => BitcoinTransaction,
+        'card'                    => Card,
+        'charge'                  => Charge,
+        'country_spec'            => CountrySpec,
+        'coupon'                  => Coupon,
+        'customer'                => Customer,
+        'dispute'                 => Dispute,
+        'event'                   => Event,
+        'fee_refund'              => ApplicationFeeRefund,
+        'file_upload'             => FileUpload,
+        'invoice'                 => Invoice,
+        'invoiceitem'             => InvoiceItem,
+        'order'                   => Order,
+        'order_return'            => OrderReturn,
+        'plan'                    => Plan,
+        'product'                 => Product,
+        'recipient'               => Recipient,
+        'refund'                  => Refund,
+        'sku'                     => SKU,
+        'subscription'            => Subscription,
+        'subscription_item'       => SubscriptionItem,
+        'three_d_secure'          => ThreeDSecure,
+        'token'                   => Token,
+        'transfer'                => Transfer,
+        'transfer_reversal'       => Reversal,
       }
     end
 
-    def self.convert_to_stripe_object(resp, opts)
-      case resp
+    # Converts a hash of fields or an array of hashes into a +StripeObject+ or
+    # array of +StripeObject+s. These new objects will be created as a concrete
+    # type as dictated by their `object` field (e.g. an `object` value of
+    # `charge` would create an instance of +Charge+), but if `object` is not
+    # present or of an unknown type, the newly created instance will fall back
+    # to being a +StripeObject+.
+    #
+    # ==== Attributes
+    #
+    # * +data+ - Hash of fields and values to be converted into a StripeObject.
+    # * +opts+ - Options for +StripeObject+ like an API key that will be reused
+    #   on subsequent API calls.
+    def self.convert_to_stripe_object(data, opts)
+      case data
       when Array
-        resp.map { |i| convert_to_stripe_object(i, opts) }
+        data.map { |i| convert_to_stripe_object(i, opts) }
       when Hash
         # Try converting to a known object class.  If none available, fall back to generic StripeObject
-        object_classes.fetch(resp[:object], StripeObject).construct_from(resp, opts)
+        object_classes.fetch(data[:object], StripeObject).construct_from(data, opts)
       else
-        resp
+        data
       end
     end
 
@@ -103,6 +121,20 @@ module Stripe
         map { |k,v| "#{url_encode(k)}=#{url_encode(v)}" }.join('&')
     end
 
+    # Transforms an array into a hash with integer keys. Used for a small
+    # number of API endpoints. If the argument is not an Array, return it
+    # unchanged. Example: [{foo: 'bar'}] => {"0" => {foo: "bar"}}
+    def self.array_to_hash(array)
+      case array
+      when Array
+        hash = {}
+        array.each_with_index { |v,i| hash[i.to_s] = v }
+        hash
+      else
+        array
+      end
+    end
+
     # Encodes a string in a way that makes it suitable for use in a set of
     # query parameters in a URI or in a set of form parameters in a request
     # body.
@@ -119,11 +151,12 @@ module Stripe
 
       # do not sort the final output because arrays (and arrays of hashes
       # especially) can be order sensitive, but do sort incoming parameters
-      params.sort_by { |(k, v)| k.to_s }.each do |key, value|
+      params.each do |key, value|
         calculated_key = parent_key ? "#{parent_key}[#{key}]" : "#{key}"
         if value.is_a?(Hash)
           result += flatten_params(value, calculated_key)
         elsif value.is_a?(Array)
+          check_array_of_maps_start_keys!(value)
           result += flatten_params_array(value, calculated_key)
         else
           result << [calculated_key, value]
@@ -180,5 +213,44 @@ module Stripe
       raise TypeError.new("api_key must be a string") unless key.is_a?(String)
       key
     end
+
+    private
+
+    # We use a pretty janky version of form encoding (Rack's) that supports
+    # more complex data structures like maps and arrays through the use of
+    # specialized syntax. To encode an array of maps like:
+    #
+    #     [{a: 1, b: 2}, {a: 3, b: 4}]
+    #
+    # We have to produce something that looks like this:
+    #
+    #     arr[][a]=1&arr[][b]=2&arr[][a]=3&arr[][b]=4
+    #
+    # The only way for the server to recognize that this is a two item array is
+    # that it notices the repetition of element "a", so it's key that these
+    # repeated elements are encoded first.
+    #
+    # This method is invoked for any arrays being encoded and checks that if
+    # the array contains all non-empty maps, that each of those maps must start
+    # with the same key so that their boundaries can be properly encoded.
+    def self.check_array_of_maps_start_keys!(arr)
+      expected_key = nil
+      arr.each do |item|
+        return if !item.is_a?(Hash)
+        return if item.count == 0
+
+        first_key = item.first[0]
+
+        if expected_key
+          if expected_key != first_key
+            raise ArgumentError,
+              "All maps nested in an array should start with the same key " +
+              "(expected starting key '#{expected_key}', got '#{first_key}')"
+          end
+        else
+          expected_key = first_key
+        end
+      end
+    end
   end
 end

data/lib/stripe/version.rb

@@ -1,3 +1,3 @@
 module Stripe
-  VERSION = '1.30.3'
+  VERSION = '2.0.0'
 end