Support sending parameters inside singleton retrieve

lib/stripe/singleton_api_resource.rb

@@ -17,8 +17,25 @@ def resource_url
       self.class.resource_url
     end
 
-    def self.retrieve(opts = {})
-      instance = new(nil, Util.normalize_opts(opts))
+    def self.retrieve(params_or_opts = {}, definitely_opts = nil)
+      opts = nil
+      params = nil
+      if definitely_opts.nil?
+        unrecognized_key = params_or_opts.keys.find { |k| !Util::OPTS_USER_SPECIFIED.include?(k) }
+        if unrecognized_key
+          raise ArgumentError,
+                "Unrecognized request option: #{unrecognized_key}. Did you mean to specify this as retrieve params? " \
+                "If so, you must explicitly pass an opts hash as a second argument. " \
+                "For example: .retrieve({#{unrecognized_key}: 'foo'}, {})"
+        end
+
+        opts = params_or_opts
+      else
+        opts = definitely_opts
+        params = params_or_opts
+      end
+
+      instance = new(params, Util.normalize_opts(opts))
       instance.refresh
       instance
     end

test/stripe/balance_test.rb

@@ -4,10 +4,40 @@
 
 module Stripe
   class BalanceTest < Test::Unit::TestCase
-    should "be retrievable" do
+    should "be retrievable with no arguments" do
       balance = Stripe::Balance.retrieve
       assert_requested :get, "#{Stripe.api_base}/v1/balance"
       assert balance.is_a?(Stripe::Balance)
     end
+    should "be retrievable with opts only" do
+      balance = Stripe::Balance.retrieve({ stripe_account: "acct_123" })
+      assert_requested :get, "#{Stripe.api_base}/v1/balance" do |req|
+        assert_equal("acct_123", req.headers["Stripe-Account"])
+        true
+      end
+      assert balance.is_a?(Stripe::Balance)
+    end
+    should "be retrievable with opts and params" do
+      balance = Stripe::Balance.retrieve({ expand: ["available"] }, { stripe_account: "acct_123" })
+      assert_requested :get, "#{Stripe.api_base}/v1/balance?expand[]=available" do |req|
+        assert_equal("acct_123", req.headers["Stripe-Account"])
+        true
+      end
+      assert balance.is_a?(Stripe::Balance)
+    end
+    should "be retrievable with params and an explicitly empty opts" do
+      balance = Stripe::Balance.retrieve({ expand: ["available"] }, {})
+      assert_requested :get, "#{Stripe.api_base}/v1/balance?expand[]=available" do |req|
+        assert_nil(req.headers["Stripe-Account"])
+        true
+      end
+      assert balance.is_a?(Stripe::Balance)
+    end
+    should "warn you if you are attempting to pass only params" do
+      exception = assert_raises(ArgumentError) do
+        Stripe::Balance.retrieve({ expand: ["available"] })
+      end
+      assert_match(/Unrecognized request option/, exception.message)
+    end
   end
 end