stripe 4.21.3 → 5.52.0

data/README.md

@@ -1,7 +1,7 @@
 # Stripe Ruby Library
 
+[![Gem Version](https://badge.fury.io/rb/stripe.svg)](https://badge.fury.io/rb/stripe)
 [![Build Status](https://travis-ci.org/stripe/stripe-ruby.svg?branch=master)](https://travis-ci.org/stripe/stripe-ruby)
-[![Coverage Status](https://coveralls.io/repos/github/stripe/stripe-ruby/badge.svg?branch=master)](https://coveralls.io/github/stripe/stripe-ruby?branch=master)
 
 The Stripe Ruby library provides convenient access to the Stripe API from
 applications written in the Ruby language. It includes a pre-defined set of
@@ -13,14 +13,15 @@ The library also provides other features. For example:
 
 - Easy configuration path for fast setup and use.
 - Helpers for pagination.
-- Tracking of "fresh" values in API resources so that partial updates can be
-  executed.
 - Built-in mechanisms for the serialization of parameters according to the
   expectations of Stripe's API.
 
 ## Documentation
 
-See the [Ruby API docs](https://stripe.com/docs/api/ruby#intro).
+See the [Ruby API docs](https://stripe.com/docs/api?lang=ruby).
+
+See [video demonstrations][youtube-playlist] covering how to use the library.
+
 
 ## Installation
 
@@ -39,7 +40,7 @@ gem build stripe.gemspec
 
 ### Requirements
 
-- Ruby 2.1+.
+- Ruby 2.3+.
 
 ### Bundler
 
@@ -61,16 +62,14 @@ available in your [Stripe Dashboard][api-keys]. Set `Stripe.api_key` to its
 value:
 
 ```ruby
-require "stripe"
-Stripe.api_key = "sk_test_..."
+require 'stripe'
+Stripe.api_key = 'sk_test_...'
 
-# list charges
-Stripe::Charge.list()
+# list customers
+Stripe::Customer.list()
 
-# retrieve single charge
-Stripe::Charge.retrieve(
-  "ch_18atAXCdGbJFKhCuBAa4532Z",
-)
+# retrieve single customer
+Stripe::Customer.retrieve('cus_123456789')
 ```
 
 ### Per-request Configuration
@@ -82,49 +81,64 @@ per-request key and/or account:
 ```ruby
 require "stripe"
 
-Stripe::Charge.list(
+Stripe::Customer.list(
   {},
   {
-    api_key: "sk_test_...",
-    stripe_account: "acct_...",
-    stripe_version: "2018-02-28",
+    api_key: 'sk_test_...',
+    stripe_account: 'acct_...',
+    stripe_version: '2018-02-28',
   }
 )
 
-Stripe::Charge.retrieve(
-  "ch_18atAXCdGbJFKhCuBAa4532Z",
+Stripe::Customer.retrieve(
+  'cus_123456789',
   {
-    api_key: "sk_test_...",
-    stripe_account: "acct_...",
-    stripe_version: "2018-02-28",
+    api_key: 'sk_test_...',
+    stripe_account: 'acct_...',
+    stripe_version: '2018-02-28',
   }
 )
 
-Stripe::Charge.retrieve(
+Stripe::Customer.retrieve(
   {
-    id: "ch_18atAXCdGbJFKhCuBAa4532Z",
+    id: 'cus_123456789',
     expand: %w(balance_transaction)
   },
   {
-    stripe_version: "2018-02-28",
-    api_key: "sk_test_...",
+    stripe_version: '2018-02-28',
+    api_key: 'sk_test_...',
+  }
+)
+
+Stripe::Customer.capture(
+  'cus_123456789',
+  {},
+  {
+    stripe_version: '2018-02-28',
+    api_key: 'sk_test_...',
   }
 )
 ```
 
-### Configuring a Client
+Keep in mind that there are different method signatures depending on the action:
+
+- When operating on a collection (e.g. `.list`, `.create`) the method signature is
+  `method(params, opts)`.
+- When operating on resource (e.g. `.capture`, `.update`) the method signature is
+  `method(id, params, opts)`.
+- One exception is that `retrieve`, despite being an operation on a resource, has the signature
+  `retrieve(id, opts)`. In addition, it will accept a Hash for the `id` param but will extract the
+  `id` key out and use the others as options.
+
+### Accessing a response object
 
-While a default HTTP client is used by default, it's also possible to have the
-library use any client supported by [Faraday][faraday] by initializing a
-`Stripe::StripeClient` object and giving it a connection:
+Get access to response objects by initializing a client and using its `request`
+method:
 
 ```ruby
-conn = Faraday.new
-client = Stripe::StripeClient.new(conn)
-charge, resp = client.request do
-  Stripe::Charge.retrieve(
-    "ch_18atAXCdGbJFKhCuBAa4532Z",
-  )
+client = Stripe::StripeClient.new
+customer, resp = client.request do
+  Stripe::Customer.retrieve('cus_123456789',)
 end
 puts resp.request_id
 ```
@@ -134,7 +148,7 @@ puts resp.request_id
 A proxy can be configured with `Stripe.proxy`:
 
 ```ruby
-Stripe.proxy = "https://user:pass@example.com:1234"
+Stripe.proxy = 'https://user:pass@example.com:1234'
 ```
 
 ### Configuring an API Version
@@ -143,7 +157,7 @@ By default, the library will use the API version pinned to the account making
 a request. This can be overridden with this global option:
 
 ```ruby
-Stripe.api_version = "2018-02-28"
+Stripe.api_version = '2018-02-28'
 ```
 
 See [versioning in the API reference][versioning] for more information.
@@ -154,28 +168,32 @@ By default, the library will use its own internal bundle of known CA
 certificates, but it's possible to configure your own:
 
 ```ruby
-Stripe.ca_bundle_path = "path/to/ca/bundle"
+Stripe.ca_bundle_path = 'path/to/ca/bundle'
 ```
 
 ### Configuring Automatic Retries
 
-The library can be configured to automatically retry requests that fail due to
-an intermittent network problem:
+You can enable automatic retries on requests that fail due to a transient
+problem by configuring the maximum number of retries:
 
 ```ruby
 Stripe.max_network_retries = 2
 ```
 
+Various errors can trigger a retry, like a connection error or a timeout, and
+also certain API responses like HTTP status `409 Conflict`.
+
 [Idempotency keys][idempotency-keys] are added to requests to guarantee that
 retries are safe.
 
 ### Configuring Timeouts
 
-Open and read timeouts are configurable:
+Open, read and write timeouts are configurable:
 
 ```ruby
-Stripe.open_timeout = 30 // in seconds
+Stripe.open_timeout = 30 # in seconds
 Stripe.read_timeout = 80
+Stripe.write_timeout = 30 # only supported on Ruby 2.6+
 ```
 
 Please take care to set conservative read timeouts. Some API requests can take
@@ -202,13 +220,63 @@ There are a few options for enabling it:
    Stripe.log_level = Stripe::LEVEL_INFO
    ```
 
+### Instrumentation
+
+The library has various hooks that user code can tie into by passing a block to
+`Stripe::Instrumentation.subscribe` to be notified about specific events.
+
+#### `request_begin`
+
+Invoked when an HTTP request starts. Receives `RequestBeginEvent` with the
+following properties:
+
+- `method`: HTTP method. (`Symbol`)
+- `path`: Request path. (`String`)
+- `user_data`: A hash on which users can set arbitrary data, and which will be
+  passed through to `request_end` invocations. This could be used, for example,
+  to assign unique IDs to each request, and it'd work even if many requests are
+  running in parallel. All subscribers share the same object for any particular
+  request, so they must be careful to use unique keys that will not conflict
+  with other subscribers. (`Hash`)
+
+#### `request_end`
+
+Invoked when an HTTP request finishes, regardless of whether it terminated with
+a success or error. Receives `RequestEndEvent` with the following properties:
+
+- `duration`: Request duration in seconds. (`Float`)
+- `http_status`: HTTP response code (`Integer`) if available, or `nil` in case
+  of a lower level network error.
+- `method`: HTTP method. (`Symbol`)
+- `num_retries`: The number of retries. (`Integer`)
+- `path`: Request path. (`String`)
+- `user_data`: A hash on which users may have set arbitrary data in
+  `request_begin`. See above for more information. (`Hash`)
+- `request_id`. HTTP request identifier.
+
+#### Example
+
+For example:
+
+```ruby
+Stripe::Instrumentation.subscribe(:request_end) do |request_event|
+  tags = {
+    method: request_event.method,
+    resource: request_event.path.split('/')[2],
+    code: request_event.http_status,
+    retries: request_event.num_retries
+  }
+  StatsD.distribution('stripe_request', request_event.duration, tags: tags)
+end
+```
+
 ### Writing a Plugin
 
 If you're writing a plugin that uses the library, we'd appreciate it if you
 identified using `#set_app_info`:
 
 ```ruby
-Stripe.set_app_info("MyAwesomePlugin", version: "1.2.34", url: "https://myawesomeplugin.info");
+Stripe.set_app_info('MyAwesomePlugin', version: '1.2.34', url: 'https://myawesomeplugin.info')
 ```
 
 This information is passed along when the library makes calls to the Stripe
@@ -272,10 +340,10 @@ Update the bundled [stripe-mock] by editing the version number found in
 [api-keys]: https://dashboard.stripe.com/account/apikeys
 [connect]: https://stripe.com/connect
 [curl]: http://curl.haxx.se/docs/caextract.html
-[faraday]: https://github.com/lostisland/faraday
-[idempotency-keys]: https://stripe.com/docs/api/ruby#idempotent_requests
+[idempotency-keys]: https://stripe.com/docs/api/idempotent_requests?lang=ruby
 [stripe-mock]: https://github.com/stripe/stripe-mock
-[versioning]: https://stripe.com/docs/api/ruby#versioning
+[versioning]: https://stripe.com/docs/api/versioning?lang=ruby
+[youtube-playlist]: https://www.youtube.com/playlist?list=PLy1nL-pvL2M50RmP6ie-gdcSnfOuQCRYk
 
 <!--
 # vim: set tw=79:

data/Rakefile

@@ -13,7 +13,8 @@ RuboCop::RakeTask.new
 
 desc "Update bundled certs"
 task :update_certs do
-  require "faraday"
+  require "net/http"
+  require "uri"
 
   fetch_file "https://curl.haxx.se/ca/cacert.pem",
              ::File.expand_path("../lib/data/ca-certificates.crt", __FILE__)
@@ -23,14 +24,14 @@ end
 # helpers
 #
 
-def fetch_file(url, dest)
+def fetch_file(uri, dest)
   ::File.open(dest, "w") do |file|
-    resp = Faraday.get(url)
-    unless resp.status == 200
-      abort("bad response when fetching: #{url}\n" \
-        "Status #{resp.status}: #{resp.body}")
+    resp = Net::HTTP.get_response(URI.parse(uri))
+    unless resp.code.to_i == 200
+      abort("bad response when fetching: #{uri}\n" \
+        "Status #{resp.code}: #{resp.body}")
     end
     file.write(resp.body)
-    puts "Successfully fetched: #{url}"
+    puts "Successfully fetched: #{uri}"
   end
 end

data/VERSION

@@ -1 +1 @@
-4.21.3
+5.52.0

data/lib/stripe/api_operations/create.rb

@@ -4,7 +4,7 @@ module Stripe
   module APIOperations
     module Create
       def create(params = {}, opts = {})
-        resp, opts = request(:post, resource_url, params, opts)
+        resp, opts = execute_resource_request(:post, resource_url, params, opts)
         Util.convert_to_stripe_object(resp.data, opts)
       end
     end

data/lib/stripe/api_operations/delete.rb

@@ -15,15 +15,19 @@ module Stripe
         # * +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}.
+        #   api_key to be overwritten. See
+        #   {APIOperations::Request.execute_resource_request}.
         def delete(id, params = {}, opts = {})
-          resp, opts = request(:delete, "#{resource_url}/#{id}", params, opts)
+          resp, opts = execute_resource_request(:delete,
+                                                "#{resource_url}/#{id}",
+                                                params, opts)
           Util.convert_to_stripe_object(resp.data, opts)
         end
       end
 
       def delete(params = {}, opts = {})
-        resp, opts = request(:delete, resource_url, params, opts)
+        resp, opts = execute_resource_request(:delete, resource_url,
+                                              params, opts)
         initialize_from(resp.data, opts)
       end
 

data/lib/stripe/api_operations/list.rb

@@ -6,25 +6,14 @@ module Stripe
       def list(filters = {}, opts = {})
         opts = Util.normalize_opts(opts)
 
-        resp, opts = request(:get, resource_url, filters, opts)
+        resp, opts = execute_resource_request(:get, resource_url, filters, opts)
         obj = ListObject.construct_from(resp.data, opts)
 
         # set filters so that we can fetch the same limit, expansions, and
         # predicates when accessing the next and previous pages
-        #
-        # just for general cleanliness, remove any paging options
         obj.filters = filters.dup
-        obj.filters.delete(:ending_before)
-        obj.filters.delete(:starting_after)
-
         obj
       end
-
-      # The original version of #list was given the somewhat unfortunate name of
-      # #all, and this alias allows us to maintain backward compatibility (the
-      # choice was somewhat misleading in the way that it only returned a single
-      # page rather than all objects).
-      alias all list
     end
   end
 end

data/lib/stripe/api_operations/nested_resource.rb

@@ -6,7 +6,7 @@ module Stripe
     # that it's possible to do so from a static context (i.e. without a
     # pre-existing collection of subresources on the parent).
     #
-    # For examle, a transfer gains the static methods for reversals so that the
+    # For example, a transfer gains the static methods for reversals so that the
     # methods `.create_reversal`, `.retrieve_reversal`, `.update_reversal`,
     # etc. all become available.
     module NestedResource
@@ -14,9 +14,11 @@ module Stripe
                                         resource_plural: nil)
         resource_plural ||= "#{resource}s"
         path ||= resource_plural
+
         raise ArgumentError, "operations array required" if operations.nil?
 
         resource_url_method = :"#{resource}s_url"
+
         define_singleton_method(resource_url_method) do |id, nested_id = nil|
           url = "#{resource_url}/#{CGI.escape(id)}/#{CGI.escape(path)}"
           url += "/#{CGI.escape(nested_id)}" unless nested_id.nil?
@@ -27,39 +29,40 @@ module Stripe
           case operation
           when :create
             define_singleton_method(:"create_#{resource}") \
-                do |id, params = {}, opts = {}|
-              url = send(resource_url_method, id)
-              resp, opts = request(:post, url, params, opts)
-              Util.convert_to_stripe_object(resp.data, opts)
-            end
+              do |id, params = {}, opts = {}|
+                url = send(resource_url_method, id)
+                resp, opts = execute_resource_request(:post, url, params, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
           when :retrieve
             define_singleton_method(:"retrieve_#{resource}") \
-                do |id, nested_id, opts = {}|
-              url = send(resource_url_method, id, nested_id)
-              resp, opts = request(:get, url, {}, opts)
-              Util.convert_to_stripe_object(resp.data, opts)
-            end
+              do |id, nested_id, opts = {}|
+                url = send(resource_url_method, id, nested_id)
+                resp, opts = execute_resource_request(:get, url, {}, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
           when :update
             define_singleton_method(:"update_#{resource}") \
-                do |id, nested_id, params = {}, opts = {}|
-              url = send(resource_url_method, id, nested_id)
-              resp, opts = request(:post, url, params, opts)
-              Util.convert_to_stripe_object(resp.data, opts)
-            end
+              do |id, nested_id, params = {}, opts = {}|
+                url = send(resource_url_method, id, nested_id)
+                resp, opts = execute_resource_request(:post, url, params, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
           when :delete
             define_singleton_method(:"delete_#{resource}") \
-                do |id, nested_id, params = {}, opts = {}|
-              url = send(resource_url_method, id, nested_id)
-              resp, opts = request(:delete, url, params, opts)
-              Util.convert_to_stripe_object(resp.data, opts)
-            end
+              do |id, nested_id, params = {}, opts = {}|
+                url = send(resource_url_method, id, nested_id)
+                resp, opts = execute_resource_request(:delete, url, params,
+                                                      opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
           when :list
             define_singleton_method(:"list_#{resource_plural}") \
-                do |id, params = {}, opts = {}|
-              url = send(resource_url_method, id)
-              resp, opts = request(:get, url, params, opts)
-              Util.convert_to_stripe_object(resp.data, opts)
-            end
+              do |id, params = {}, opts = {}|
+                url = send(resource_url_method, id)
+                resp, opts = execute_resource_request(:get, url, params, opts)
+                Util.convert_to_stripe_object(resp.data, opts)
+              end
           else
             raise ArgumentError, "Unknown operation: #{operation.inspect}"
           end

data/lib/stripe/api_operations/request.rb

@@ -4,10 +4,38 @@ module Stripe
   module APIOperations
     module Request
       module ClassMethods
-        def request(method, url, params = {}, opts = {})
+        def execute_resource_request(method, url,
+                                     params = {}, opts = {})
+          execute_resource_request_internal(
+            :execute_request, method, url, params, opts
+          )
+        end
+
+        def execute_resource_request_stream(method, url,
+                                            params = {}, opts = {},
+                                            &read_body_chunk_block)
+          execute_resource_request_internal(
+            :execute_request_stream,
+            method,
+            url,
+            params,
+            opts,
+            &read_body_chunk_block
+          )
+        end
+
+        private def execute_resource_request_internal(client_request_method_sym,
+                                                      method, url,
+                                                      params, opts,
+                                                      &read_body_chunk_block)
+          params ||= {}
+
+          error_on_invalid_params(params)
           warn_on_opts_in_params(params)
 
           opts = Util.normalize_opts(opts)
+          error_on_non_string_user_opts(opts)
+
           opts[:client] ||= StripeClient.active_client
 
           headers = opts.clone
@@ -16,10 +44,12 @@ module Stripe
           client = headers.delete(:client)
           # Assume all remaining opts must be headers
 
-          resp, opts[:api_key] = client.execute_request(
+          resp, opts[:api_key] = client.send(
+            client_request_method_sym,
             method, url,
             api_base: api_base, api_key: api_key,
-            headers: headers, params: params
+            headers: headers, params: params,
+            &read_body_chunk_block
           )
 
           # Hash#select returns an array before 1.9
@@ -31,10 +61,43 @@ module Stripe
           [resp, opts_to_persist]
         end
 
+        # This method used to be called `request`, but it's such a short name
+        # that it eventually conflicted with the name of a field on an API
+        # resource (specifically, `Event#request`), so it was renamed to
+        # something more unique.
+        #
+        # The former name had been around for just about forever though, and
+        # although all internal uses have been renamed, I've left this alias in
+        # place for backwards compatibility. Consider removing it on the next
+        # major.
+        alias request execute_resource_request
+
+        private def error_on_non_string_user_opts(opts)
+          Util::OPTS_USER_SPECIFIED.each do |opt|
+            next unless opts.key?(opt)
+
+            val = opts[opt]
+            next if val.nil?
+            next if val.is_a?(String)
+
+            raise ArgumentError,
+                  "request option '#{opt}' should be a string value " \
+                    "(was a #{val.class})"
+          end
+        end
+
+        private def error_on_invalid_params(params)
+          return if params.nil? || params.is_a?(Hash)
+
+          raise ArgumentError,
+                "request params should be either a Hash or nil " \
+                  "(was a #{params.class})"
+        end
+
         private def warn_on_opts_in_params(params)
           Util::OPTS_USER_SPECIFIED.each do |opt|
             if params.key?(opt)
-              warn("WARNING: #{opt} should be in opts instead of params.")
+              warn("WARNING: '#{opt}' should be in opts instead of params.")
             end
           end
         end
@@ -44,10 +107,23 @@ module Stripe
         base.extend(ClassMethods)
       end
 
-      protected def request(method, url, params = {}, opts = {})
+      protected def execute_resource_request(method, url,
+                                             params = {}, opts = {})
         opts = @opts.merge(Util.normalize_opts(opts))
-        self.class.request(method, url, params, opts)
+        self.class.execute_resource_request(method, url, params, opts)
       end
+
+      protected def execute_resource_request_stream(method, url,
+                                                    params = {}, opts = {},
+                                                    &read_body_chunk_block)
+        opts = @opts.merge(Util.normalize_opts(opts))
+        self.class.execute_resource_request_stream(
+          method, url, params, opts, &read_body_chunk_block
+        )
+      end
+
+      # See notes on `alias` above.
+      alias request execute_resource_request
     end
   end
 end

data/lib/stripe/api_operations/save.rb

@@ -15,7 +15,8 @@ module Stripe
         # * +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}.
+        #   api_key to be overwritten. See
+        #   {APIOperations::Request.execute_resource_request}.
         def update(id, params = {}, opts = {})
           params.each_key do |k|
             if protected_fields.include?(k)
@@ -23,7 +24,8 @@ module Stripe
             end
           end
 
-          resp, opts = request(:post, "#{resource_url}/#{id}", params, opts)
+          resp, opts = execute_resource_request(:post, "#{resource_url}/#{id}",
+                                                params, opts)
           Util.convert_to_stripe_object(resp.data, opts)
         end
       end
@@ -43,7 +45,8 @@ module Stripe
       # * +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}.
+      #   api_key to be overwritten. See
+      #   {APIOperations::Request.execute_resource_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
@@ -59,7 +62,7 @@ module Stripe
         # generated a uri for this object with an identifier baked in
         values.delete(:id)
 
-        resp, opts = request(:post, save_url, values, opts)
+        resp, opts = execute_resource_request(:post, save_url, values, opts)
         initialize_from(resp.data, opts)
       end
 

data/lib/stripe/api_operations/search.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Stripe
+  module APIOperations
+    module Search
+      def _search(search_url, filters = {}, opts = {})
+        opts = Util.normalize_opts(opts)
+
+        resp, opts = execute_resource_request(:get, search_url, filters, opts)
+        obj = SearchResultObject.construct_from(resp.data, opts)
+
+        # set filters so that we can fetch the same limit and query
+        # when accessing the next page
+        obj.filters = filters.dup
+        obj
+      end
+    end
+  end
+end