stripe 1.31.0 → 1.58.0

data/lib/stripe/account.rb

@@ -1,11 +1,18 @@
 module Stripe
   class Account < APIResource
+    extend Gem::Deprecate
     extend Stripe::APIOperations::Create
-    include Stripe::APIOperations::Delete
     extend Stripe::APIOperations::List
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Delete
+    include Stripe::APIOperations::Save
+
+    save_nested_resource :external_account
 
-    def url
+    # This method is deprecated. Please use `#external_account=` instead.
+    save_nested_resource :bank_account
+    deprecate :bank_account=, "#external_account=", 2017, 8
+
+    def resource_url
       if self['id']
         super
       else
@@ -25,10 +32,15 @@ module Stripe
         opts = id
         id = nil
       end
-
       super(id, opts)
     end
 
+    def reject(params={}, opts={})
+      opts = Util.normalize_opts(opts)
+      response, opts = request(:post, resource_url + '/reject', params, opts)
+      initialize_from(response, opts)
+    end
+
     # Somewhat unfortunately, we attempt to do a special encoding trick when
     # serializing `additional_owners` under an account: when updating a value,
     # we actually send the update parameters up as an integer-indexed hash
@@ -52,21 +64,22 @@ module Stripe
     #
     # We're trying to get this overturned on the server side, but for now,
     # patch in a special allowance.
-    def self.serialize_params(obj, original_value=nil)
-      update_hash = StripeObject.serialize_params(obj, original_value)
-      case obj
-      when StripeObject
-        obj_values = obj.instance_variable_get(:@values)
-        obj_values.each do |k, v|
-          if k == :additional_owners && v.is_a?(Array)
-            update_hash[k] = serialize_additional_owners(obj, v)
-          end
+    def serialize_params(options = {})
+      serialize_params_account(self, super)
+    end
+
+    def serialize_params_account(obj, update_hash)
+      if entity = @values[:legal_entity]
+        if owners = entity[:additional_owners]
+          entity_update = update_hash[:legal_entity] ||= {}
+          entity_update[:additional_owners] =
+            serialize_additional_owners(entity, owners)
         end
       end
       update_hash
     end
 
-    def protected_fields
+    def self.protected_fields
       [:legal_entity]
     end
 
@@ -89,9 +102,9 @@ module Stripe
 
     private
 
-    def self.serialize_additional_owners(obj, value)
-      original_value = obj.instance_variable_get(:@original_values)[:additional_owners]
-      if original_value && original_value.length > value.length
+    def serialize_additional_owners(legal_entity, additional_owners)
+      original_value = legal_entity.instance_variable_get(:@original_values)[:additional_owners]
+      if original_value && original_value.length > additional_owners.length
         # url params provide no mechanism for deleting an item in an array,
         # just overwriting the whole array or adding new items. So let's not
         # allow deleting without a full overwrite until we have a solution.
@@ -101,10 +114,17 @@ module Stripe
       end
 
       update_hash = {}
-      value.each_with_index do |v, i|
-        update = StripeObject.serialize_params(v)
-        if update != {} && (!original_value || update != original_value[i])
-          update_hash[i.to_s] = update
+      additional_owners.each_with_index do |v, i|
+        # We will almost always see a StripeObject except in the case of a Hash
+        # that's been appended to an array of `additional_owners`. We may be
+        # able to normalize that ugliness by using an array proxy object with
+        # StripeObjects that can detect appends and replace a hash with a
+        # StripeObject.
+        update = v.is_a?(StripeObject) ? v.serialize_params : v
+
+        if update != {} && (!original_value ||
+          update != legal_entity.serialize_params_value(original_value[i], nil, false, true))
+            update_hash[i.to_s] = update
         end
       end
       update_hash

data/lib/stripe/alipay_account.rb

@@ -0,0 +1,20 @@
+module Stripe
+  class AlipayAccount < APIResource
+    include Stripe::APIOperations::Save
+    include Stripe::APIOperations::Delete
+
+    def resource_url
+      if respond_to?(:customer) && !self.customer.nil?
+        "#{Customer.resource_url}/#{CGI.escape(customer)}/sources/#{CGI.escape(id)}"
+      end
+    end
+
+    def self.update(id, params=nil, opts=nil)
+      raise NotImplementedError.new("Alipay accounts cannot be updated without a customer ID. Update an Alipay account by `a = customer.sources.retrieve('alipay_account_id'); a.save`")
+    end
+
+    def self.retrieve(id, opts=nil)
+      raise NotImplementedError.new("Alipay accounts cannot be retrieved without a customer ID. Retrieve an Alipay account using customer.sources.retrieve('alipay_account_id')")
+    end
+  end
+end

data/lib/stripe/api_operations/create.rb

@@ -2,7 +2,7 @@ module Stripe
   module APIOperations
     module Create
       def create(params={}, opts={})
-        response, opts = request(:post, url, params, opts)
+        response, opts = request(:post, resource_url, params, opts)
         Util.convert_to_stripe_object(response, opts)
       end
     end

data/lib/stripe/api_operations/delete.rb

@@ -3,7 +3,7 @@ module Stripe
     module Delete
       def delete(params={}, opts={})
         opts = Util.normalize_opts(opts)
-        response, opts = request(:delete, url, params, opts)
+        response, opts = request(:delete, resource_url, params, opts)
         initialize_from(response, opts)
       end
     end

data/lib/stripe/api_operations/list.rb

@@ -3,9 +3,8 @@ module Stripe
     module List
       def list(filters={}, opts={})
         opts = Util.normalize_opts(opts)
-        opts = @opts.merge(opts) if @opts
 
-        response, opts = request(:get, url, filters, opts)
+        response, opts = request(:get, resource_url, filters, opts)
         obj = ListObject.construct_from(response, opts)
 
         # set filters so that we can fetch the same limit, expansions, and

data/lib/stripe/api_operations/save.rb

@@ -0,0 +1,87 @@
+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.request}.
+        def update(id, params={}, opts={})
+          params.each do |k, v|
+            if self.protected_fields.include?(k)
+              raise ArgumentError, "Cannot update protected field: #{k}"
+            end
+          end
+
+          response, opts = request(:post, "#{resource_url}/#{id}", params, opts)
+          Util.convert_to_stripe_object(response, 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.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 = self.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)
+
+        response, opts = request(:post, save_url, values, opts)
+        initialize_from(response, opts)
+
+        self
+      end
+
+      def self.included(base)
+        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

@@ -2,26 +2,59 @@ 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]
     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.)')
       end
       "/v1/#{CGI.escape(class_name.downcase)}s"
     end
 
-    def url
+    # 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.
+        if value.is_a?(APIResource)
+          value.save_with_parent = true
+        end
+
+        value
+      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.url}/#{CGI.escape(id)}"
+      "#{self.class.resource_url}/#{CGI.escape(id)}"
     end
 
     def refresh
-      response, opts = request(:get, url, @retrieve_params)
+      response, opts = request(:get, resource_url, @retrieve_params)
       initialize_from(response, opts)
     end
 

data/lib/stripe/apple_pay_domain.rb

@@ -0,0 +1,12 @@
+module Stripe
+  # Domains registered for Apple Pay on the Web
+  class ApplePayDomain < APIResource
+    extend Stripe::APIOperations::Create
+    include Stripe::APIOperations::Delete
+    extend Stripe::APIOperations::List
+
+    def self.resource_url
+      '/v1/apple_pay/domains'
+    end
+  end
+end

data/lib/stripe/application_fee.rb

@@ -2,19 +2,19 @@ module Stripe
   class ApplicationFee < APIResource
     extend Stripe::APIOperations::List
 
-    def self.url
+    def self.resource_url
       '/v1/application_fees'
     end
 
+    # If you don't need access to an updated fee object after the refund, it's
+    # more performant to just call `fee.refunds.create` directly.
     def refund(params={}, opts={})
-      response, opts = request(:post, refund_url, params, opts)
-      initialize_from(response, opts)
-    end
-
-    private
+      self.refunds.create(params, opts)
 
-    def refund_url
-      url + '/refund'
+      # now that a refund has been created, we expect the state of this object
+      # to change as well (i.e. `refunded` will now be `true`) so refresh it
+      # from the server
+      self.refresh
     end
   end
 end

data/lib/stripe/application_fee_refund.rb

@@ -1,10 +1,14 @@
 module Stripe
   class ApplicationFeeRefund < APIResource
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
     extend Stripe::APIOperations::List
 
-    def url
-      "#{ApplicationFee.url}/#{CGI.escape(fee)}/refunds/#{CGI.escape(id)}"
+    def resource_url
+      "#{ApplicationFee.resource_url}/#{CGI.escape(fee)}/refunds/#{CGI.escape(id)}"
+    end
+
+    def self.update(id, params=nil, opts=nil)
+      raise NotImplementedError.new("Refunds cannot be updated without an application fee ID. Update a refund by using `a = appfee.refunds.retrieve('refund_id'); a.save`")
     end
 
     def self.retrieve(id, api_key=nil)

data/lib/stripe/balance_transaction.rb

@@ -2,7 +2,7 @@ module Stripe
   class BalanceTransaction < APIResource
     extend Stripe::APIOperations::List
 
-    def self.url
+    def self.resource_url
       '/v1/balance/history'
     end
   end

data/lib/stripe/bank_account.rb

@@ -1,22 +1,26 @@
 module Stripe
   class BankAccount < APIResource
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
     include Stripe::APIOperations::Delete
     extend Stripe::APIOperations::List
 
     def verify(params={}, opts={})
-      response, opts = request(:post, url + '/verify', params, opts)
+      response, opts = request(:post, resource_url + '/verify', params, opts)
       initialize_from(response, opts)
     end
 
-    def url
+    def resource_url
       if respond_to?(:customer)
-        "#{Customer.url}/#{CGI.escape(customer)}/sources/#{CGI.escape(id)}"
+        "#{Customer.resource_url}/#{CGI.escape(customer)}/sources/#{CGI.escape(id)}"
       elsif respond_to?(:account)
-        "#{Account.url}/#{CGI.escape(account)}/external_accounts/#{CGI.escape(id)}"
+        "#{Account.resource_url}/#{CGI.escape(account)}/external_accounts/#{CGI.escape(id)}"
       end
     end
 
+    def self.update(id, params=nil, opts=nil)
+      raise NotImplementedError.new("Bank accounts cannot be updated without an account ID. Update a bank account by using `a = account.external_accounts.retrieve('card_id'); a.save`")
+    end
+
     def self.retrieve(id, opts=nil)
       raise NotImplementedError.new("Bank accounts cannot be retrieved without an account ID. Retrieve a bank account using account.external_accounts.retrieve('card_id')")
     end

data/lib/stripe/bitcoin_receiver.rb

@@ -1,19 +1,19 @@
 module Stripe
   class BitcoinReceiver < APIResource
     extend Stripe::APIOperations::Create
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
     include Stripe::APIOperations::Delete
     extend Stripe::APIOperations::List
 
-    def self.url
+    def self.resource_url
       "/v1/bitcoin/receivers"
     end
 
-    def url
-      if respond_to?(:customer)
-        "#{Customer.url}/#{CGI.escape(customer)}/sources/#{CGI.escape(id)}"
+    def resource_url
+      if respond_to?(:customer) && !self.customer.nil?
+        "#{Customer.resource_url}/#{CGI.escape(customer)}/sources/#{CGI.escape(id)}"
       else
-        "#{self.class.url}/#{CGI.escape(id)}"
+        "#{self.class.resource_url}/#{CGI.escape(id)}"
       end
     end
   end

data/lib/stripe/bitcoin_transaction.rb

@@ -2,7 +2,7 @@ module Stripe
   class BitcoinTransaction < APIResource
     extend Stripe::APIOperations::List
 
-    def self.url
+    def self.resource_url
       "/v1/bitcoin/transactions"
     end
   end

data/lib/stripe/card.rb

@@ -1,19 +1,23 @@
 module Stripe
   class Card < APIResource
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
     include Stripe::APIOperations::Delete
     extend Stripe::APIOperations::List
 
-    def url
+    def resource_url
       if respond_to?(:recipient)
-        "#{Recipient.url}/#{CGI.escape(recipient)}/cards/#{CGI.escape(id)}"
+        "#{Recipient.resource_url}/#{CGI.escape(recipient)}/cards/#{CGI.escape(id)}"
       elsif respond_to?(:customer)
-        "#{Customer.url}/#{CGI.escape(customer)}/sources/#{CGI.escape(id)}"
+        "#{Customer.resource_url}/#{CGI.escape(customer)}/sources/#{CGI.escape(id)}"
       elsif respond_to?(:account)
-        "#{Account.url}/#{CGI.escape(account)}/external_accounts/#{CGI.escape(id)}"
+        "#{Account.resource_url}/#{CGI.escape(account)}/external_accounts/#{CGI.escape(id)}"
       end
     end
 
+    def self.update(id, params=nil, opts=nil)
+      raise NotImplementedError.new("Cards cannot be updated without a customer ID. Update a card using `c = customer.sources.retrieve('card_id'); c.save`")
+    end
+
     def self.retrieve(id, opts=nil)
       raise NotImplementedError.new("Cards cannot be retrieved without a customer ID. Retrieve a card using customer.sources.retrieve('card_id')")
     end

data/lib/stripe/charge.rb

@@ -2,11 +2,27 @@ module Stripe
   class Charge < APIResource
     extend Stripe::APIOperations::List
     extend Stripe::APIOperations::Create
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
 
     def refund(params={}, opts={})
-      response, opts = request(:post, refund_url, params, opts)
-      initialize_from(response, opts)
+      # Old versions of charge objects included a `refunds` field that was just
+      # a vanilla array instead of a Stripe list object.
+      #
+      # Where possible, we'd still like to use the new refund endpoint (thus
+      # `self.refunds.create`), but detect the old API version by looking for
+      # an `Array` and fall back to the old refund URL if necessary so as to
+      # maintain internal compatibility.
+      unless self.refunds.is_a?(Array)
+        self.refunds.create(params, opts)
+
+        # now that a refund has been created, we expect the state of this object
+        # to change as well (i.e. `refunded` will now be `true`) so refresh it
+        # from the server
+        self.refresh
+      else
+        response, opts = request(:post, refund_url, params, opts)
+        initialize_from(response, opts)
+      end
     end
 
     def capture(params={}, opts={})
@@ -29,7 +45,7 @@ module Stripe
       params = {
         :fraud_details => { :user_report => 'fraudulent' }
       }
-      response, opts = request(:post, url, params)
+      response, opts = request(:post, resource_url, params)
       initialize_from(response, opts)
     end
 
@@ -37,26 +53,28 @@ module Stripe
       params = {
         :fraud_details => { :user_report => 'safe' }
       }
-      response, opts = request(:post, url, params)
+      response, opts = request(:post, resource_url, params)
       initialize_from(response, opts)
     end
 
     private
 
-    def refund_url
-      url + '/refund'
-    end
-
     def capture_url
-      url + '/capture'
+      resource_url + '/capture'
     end
 
     def dispute_url
-      url + '/dispute'
+      resource_url + '/dispute'
     end
 
     def close_dispute_url
-      url + '/dispute/close'
+      resource_url + '/dispute/close'
+    end
+
+    # Note that this is actually the *old* refund URL and its use is no longer
+    # preferred.
+    def refund_url
+      resource_url + '/refund'
     end
   end
 end

data/lib/stripe/country_spec.rb

@@ -0,0 +1,9 @@
+module Stripe
+  class CountrySpec < APIResource
+    extend Stripe::APIOperations::List
+
+    def self.resource_url
+      '/v1/country_specs'
+    end
+  end
+end

data/lib/stripe/coupon.rb

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

data/lib/stripe/customer.rb

@@ -2,9 +2,11 @@ module Stripe
   class Customer < APIResource
     extend Stripe::APIOperations::Create
     include Stripe::APIOperations::Delete
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
     extend Stripe::APIOperations::List
 
+    save_nested_resource :source
+
     def add_invoice_item(params, opts={})
       opts = @opts.merge(Util.normalize_opts(opts))
       InvoiceItem.create(params.merge(:customer => id), opts)
@@ -61,15 +63,15 @@ module Stripe
     private
 
     def discount_url
-      url + '/discount'
+      resource_url + '/discount'
     end
 
     def subscription_url
-      url + '/subscription'
+      resource_url + '/subscription'
     end
 
     def subscriptions_url
-      url + '/subscriptions'
+      resource_url + '/subscriptions'
     end
   end
 end

data/lib/stripe/dispute.rb

@@ -2,7 +2,7 @@ module Stripe
   class Dispute < APIResource
     extend Stripe::APIOperations::List
     extend Stripe::APIOperations::Create
-    include Stripe::APIOperations::Update
+    include Stripe::APIOperations::Save
 
     def close(params={}, opts={})
       response, opts = request(:post, close_url, params, opts)
@@ -10,7 +10,7 @@ module Stripe
     end
 
     def close_url
-      url + '/close'
+      resource_url + '/close'
     end
   end
 end