stripe 4.24.0 → 5.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2abaedad94afb640e2ee4b39c6a825a2aa8f234d8ce5d64542d73cae0c46c92
-  data.tar.gz: c5c0f7c81270700f7abbf8adcf329268daaff092c8c4892c500ff06c6a1e2dc4
+  metadata.gz: 9055258932833823356b606115c73e9a909bbfc2e6d70506e2c71d21e2176c27
+  data.tar.gz: 4a7261f19e29f65407bff7ee8ae916c1b826e81ac4e1e9c102b6ac147c548b31
 SHA512:
-  metadata.gz: 4f3955ca4759861c3f5d2bd6c78d661239886e44d3cf25939185dc0cc1846ded39c19c71f15c1c71295d686d2cab2d3b5937c11cf0dc9364dbca9289718f02b7
-  data.tar.gz: 9d3d78053ccb35930ebf2cb7da3b4fe986e357599d53fe685b63f79799e26707354eac68b8ce70b0958ddce0375865f67158c1c843c7bd74d28f4b8f8fd3a56c
+  metadata.gz: bd7fa29256871a690e19758b6777d9ee58e51fa4cf0a7b3e576fac24deca605cdb400e7eb091378ff15540c1a48ccfd25ba0bb9befba04d6a92d95fb1202416b
+  data.tar.gz: ce6d07144a874d49e088033645916e1aa09b2e5eedf787ea1eb182ef963ffddafd314d7442a258937e028b8d84ed04c00d02c68f6a93841a262dbd5bc6e5aecd

data/CHANGELOG.md

@@ -1,5 +1,174 @@
 # Changelog
 
+## 5.36.0 - 2021-07-09
+* [#987](https://github.com/stripe/stripe-ruby/pull/987) Add support for `Quote` API
+
+## 5.35.0 - 2021-06-30
+* [#985](https://github.com/stripe/stripe-ruby/pull/985) Update normalize_opts to use dup instead of clone.
+* [#982](https://github.com/stripe/stripe-ruby/pull/982) Deprecate travis
+* [#983](https://github.com/stripe/stripe-ruby/pull/983) Add support for making a request and receiving the response as a stream.
+
+## 5.34.0 - 2021-06-04
+* [#981](https://github.com/stripe/stripe-ruby/pull/981) API Updates
+  * Add support for `TaxCode` API.
+
+## 5.33.0 - 2021-05-19
+* [#979](https://github.com/stripe/stripe-ruby/pull/979) Add support for the Identify VerificationSession and VerificationReport APIs
+
+## 5.32.1 - 2021-04-05
+* Correct use of regexp `match` in gemspec for old versions of Ruby
+
+## 5.32.0 - 2021-04-05
+* [#973](https://github.com/stripe/stripe-ruby/pull/973) Reduce packed gem size
+
+## 5.31.0 - 2021-04-02
+* [#968](https://github.com/stripe/stripe-ruby/pull/968) Allow StripeClient to be configured per instance
+* [#971](https://github.com/stripe/stripe-ruby/pull/971) On config change, only clear connection managers for changed config
+* [#972](https://github.com/stripe/stripe-ruby/pull/972) Rename `Stripe.configuration` to `Stripe.config`
+* [#970](https://github.com/stripe/stripe-ruby/pull/970) Reserve some critical field names when adding `StripeObject` accessors
+* [#967](https://github.com/stripe/stripe-ruby/pull/967) CI: github actions
+
+## 5.30.0 - 2021-02-22
+* [#965](https://github.com/stripe/stripe-ruby/pull/965) Add support for the Billing Portal Configuration API
+
+## 5.29.1 - 2021-02-09
+* [#964](https://github.com/stripe/stripe-ruby/pull/964) Fix return value of `Customer#delete_discount`
+
+## 5.29.0 - 2021-01-05
+* [#952](https://github.com/stripe/stripe-ruby/pull/952) Allow client_id configuration on instance config
+
+## 5.28.0 - 2020-10-14
+* [#950](https://github.com/stripe/stripe-ruby/pull/950) Add configuration option for `write_timeout` for connections on Ruby 2.6+
+
+## 5.27.0 - 2020-10-14
+* [#951](https://github.com/stripe/stripe-ruby/pull/951) Add support for the Payout Reverse API
+
+## 5.26.0 - 2020-09-29
+* [#949](https://github.com/stripe/stripe-ruby/pull/949) Add support for the `SetupAttempt` resource and List API
+
+## 5.25.0 - 2020-09-02
+* [#944](https://github.com/stripe/stripe-ruby/pull/944) Add support for the Issuing Dispute Submit API
+
+## 5.24.0 - 2020-08-26
+* [#939](https://github.com/stripe/stripe-ruby/pull/939) Extract configurations into separate object
+* [#940](https://github.com/stripe/stripe-ruby/pull/940) Fix typo in documentation of `stripe_object.rb`
+
+## 5.23.1 - 2020-08-05
+* [#936](https://github.com/stripe/stripe-ruby/pull/936) Rename API resource's `request` method
+
+## 5.23.0 - 2020-08-05
+* [#937](https://github.com/stripe/stripe-ruby/pull/937) Add support for the `PromotionCode` resource and APIs
+
+## 5.22.0 - 2020-05-11
+* [#918](https://github.com/stripe/stripe-ruby/pull/918) Add support for the `LineItem` resource and APIs
+
+## 5.21.0 - 2020-04-29
+* [#917](https://github.com/stripe/stripe-ruby/pull/917) Add support for the `Price` resource and APIs
+
+## 5.20.0 - 2020-04-27
+* [#916](https://github.com/stripe/stripe-ruby/pull/916) Add new `.generate_header` method for webhooks
+
+## 5.19.0 - 2020-04-24
+* [#915](https://github.com/stripe/stripe-ruby/pull/915) Expose `Stripe::Webhook.compute_signature` publicly
+
+## 5.18.0 - 2020-04-22
+* [#911](https://github.com/stripe/stripe-ruby/pull/911) Add support for `BillingPortal` namespace and `Session` resource and APIs
+
+## 5.17.0 - 2020-02-26
+* [#907](https://github.com/stripe/stripe-ruby/pull/907) Add `StripeError#idempotent_replayed?`
+
+## 5.16.0 - 2020-02-26
+* [#906](https://github.com/stripe/stripe-ruby/pull/906) Add support for listing Checkout sessions
+* [#903](https://github.com/stripe/stripe-ruby/pull/903) Upgrade to Rubocop 0.80
+
+## 5.15.0 - 2020-02-10
+* [#902](https://github.com/stripe/stripe-ruby/pull/902) Add `request_begin` instrumentation callback
+
+## 5.14.0 - 2020-01-14
+* [#896](https://github.com/stripe/stripe-ruby/pull/896) Add support for `CreditNoteLineItem`
+* [#894](https://github.com/stripe/stripe-ruby/pull/894) Clean up test output by capturing `$stderr` when we expect warnings
+* [#892](https://github.com/stripe/stripe-ruby/pull/892) Explicitly pass a parameter as hash to be more ruby 2.7 friendly
+* [#893](https://github.com/stripe/stripe-ruby/pull/893) Upgrade Rubocop to 0.79
+
+## 5.13.0 - 2020-01-08
+* [#891](https://github.com/stripe/stripe-ruby/pull/891) Fix most Ruby 2.7 warnings
+
+## 5.12.1 - 2020-01-06
+* [#890](https://github.com/stripe/stripe-ruby/pull/890) Override API key with `client_secret` in `OAuth.token`
+
+## 5.12.0 - 2020-01-02
+* [#889](https://github.com/stripe/stripe-ruby/pull/889) Add support for retrieve source transaction API method
+
+## 5.11.0 - 2019-11-26
+* [#885](https://github.com/stripe/stripe-ruby/pull/885) Add support for `CreditNote` preview
+
+## 5.10.0 - 2019-11-08
+* [#882](https://github.com/stripe/stripe-ruby/pull/882) Add list_usage_record_summaries and list_source_transactions
+
+## 5.9.0 - 2019-11-07
+* [#870](https://github.com/stripe/stripe-ruby/pull/870) Add request instrumentation callback (see `README.md` for usage example)
+
+## 5.8.0 - 2019-11-05
+* [#879](https://github.com/stripe/stripe-ruby/pull/879) Add support for `Mandate`
+* [#876](https://github.com/stripe/stripe-ruby/pull/876) Add additional per-request configuration documentation
+* [#874](https://github.com/stripe/stripe-ruby/pull/874) Raise an error when requests params are invalid
+* [#873](https://github.com/stripe/stripe-ruby/pull/873) Contributor Covenant
+
+## 5.7.1 - 2019-10-15
+* [#869](https://github.com/stripe/stripe-ruby/pull/869) Fixes the misnamed `connection_base=` setter to be named `connect_base=`
+
+## 5.7.0 - 2019-10-10
+* [#865](https://github.com/stripe/stripe-ruby/pull/865) Support backwards pagination with list's `#auto_paging_each`
+
+## 5.6.0 - 2019-10-04
+* [#861](https://github.com/stripe/stripe-ruby/pull/861) Nicer error when specifying non-nil non-string opt value
+
+## 5.5.0 - 2019-10-03
+* [#859](https://github.com/stripe/stripe-ruby/pull/859) User-friendly messages and retries for `EOFError`, `Errno::ECONNRESET`, `Errno::ETIMEDOUT`, and `Errno::EHOSTUNREACH` network errors
+
+## 5.4.1 - 2019-10-01
+* [#858](https://github.com/stripe/stripe-ruby/pull/858) Drop Timecop dependency
+
+## 5.4.0 - 2019-10-01
+* [#857](https://github.com/stripe/stripe-ruby/pull/857) Move to monotonic time for duration calculations
+
+## 5.3.0 - 2019-10-01
+* [#853](https://github.com/stripe/stripe-ruby/pull/853) Support `Stripe-Should-Retry` header
+
+## 5.2.0 - 2019-09-19
+* [#851](https://github.com/stripe/stripe-ruby/pull/851) Introduce system for garbage collecting connection managers
+
+## 5.1.1 - 2019-09-04
+* [#845](https://github.com/stripe/stripe-ruby/pull/845) Transfer the request_id from the http_headers to error.
+
+## 5.1.0 - 2019-08-27
+* [#841](https://github.com/stripe/stripe-ruby/pull/841) Retry requests on a 429 that's a lock timeout
+
+## 5.0.1 - 2019-08-20
+* [#836](https://github.com/stripe/stripe-ruby/pull/836) Increase connection keep alive timeout to 30 seconds
+
+## 5.0.0 - 2019-08-20
+Major version release. The [migration guide](https://github.com/stripe/stripe-ruby/wiki/Migration-guide-for-v5) contains a detailed list of backwards-incompatible changes with upgrade instructions.
+
+Pull requests included in this release (cf. [#815](https://github.com/stripe/stripe-ruby/pull/815)) (⚠️ = breaking changes):
+* ⚠️ [#813](https://github.com/stripe/stripe-ruby/pull/813): Convert library to use built-in `Net::HTTP`
+* ⚠️ [#816](https://github.com/stripe/stripe-ruby/pull/816): Make `code` argument in `CardError` named instead of positional.
+* ⚠️ [#817](https://github.com/stripe/stripe-ruby/pull/817): Drop support for very old Ruby versions.
+* [#818](https://github.com/stripe/stripe-ruby/pull/818): Bump Rubocop to latest version
+* [#819](https://github.com/stripe/stripe-ruby/pull/819): Ruby minimum version increase followup
+* ⚠️ [#820](https://github.com/stripe/stripe-ruby/pull/820): Remove old deprecated methods
+* ⚠️ [#823](https://github.com/stripe/stripe-ruby/pull/823): Remove all alias for list methods
+* ⚠️ [#826](https://github.com/stripe/stripe-ruby/pull/826): Remove `UsageRecord.create` method
+* ⚠️ [#827](https://github.com/stripe/stripe-ruby/pull/827): Remove `IssuerFraudRecord`
+* [#811](https://github.com/stripe/stripe-ruby/pull/811): Add `ErrorObject` to `StripeError` exceptions
+* [#828](https://github.com/stripe/stripe-ruby/pull/828): Tweak retry logic to be a little more like stripe-node
+* [#829](https://github.com/stripe/stripe-ruby/pull/829): Reset connections when connection-changing configuration changes (optional)
+* [#830](https://github.com/stripe/stripe-ruby/pull/830): Fix inverted sign for 500 retries
+* ⚠️[#831](https://github.com/stripe/stripe-ruby/pull/831): Remove a few more very old deprecated methods
+* [#832](https://github.com/stripe/stripe-ruby/pull/832): Minor cleanup in `StripeClient`
+* [#833](https://github.com/stripe/stripe-ruby/pull/833): Do better bookkeeping when tracking state in `Thread.current`
+* [#834](https://github.com/stripe/stripe-ruby/pull/834): Add `Invoice.list_upcoming_line_items` method
+
 ## 4.24.0 - 2019-08-12
 * [#825](https://github.com/stripe/stripe-ruby/pull/825) Add `SubscriptionItem.create_usage_record` method
   - This release also removed the `SubscriptionSchedule.revisions` method. This should have been included in the previous release (4.23.0)

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,77 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at conduct@stripe.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
+

data/Gemfile

@@ -5,31 +5,25 @@ source "https://rubygems.org"
 gemspec
 
 group :development do
-  gem "coveralls", require: false
   gem "mocha", "~> 0.13.2"
+  gem "rack", ">= 2.0.6"
   gem "rake"
-  gem "shoulda-context"
+
+  # Update to 2.0.0 once it ships.
+  gem "shoulda-context", "2.0.0.rc4"
+
   gem "test-unit"
-  gem "timecop"
-  gem "webmock"
+
+  # Version doesn't matter that much, but this one contains some fixes for Ruby
+  # 2.7 warnings that add noise to the test suite.
+  gem "webmock", ">= 3.8.0"
 
   # Rubocop changes pretty quickly: new cops get added and old cops change
   # names or go into new namespaces. This is a library and we don't have
   # `Gemfile.lock` checked in, so to prevent good builds from suddenly going
   # bad, pin to a specific version number here. Try to keep this relatively
   # up-to-date, but it's not the end of the world if it's not.
-  # Note that 0.57.2 is the most recent version we can use until we drop
-  # support for Ruby 2.1.
-  gem "rubocop", "0.57.2"
-
-  # Rack 2.0+ requires Ruby >= 2.2.2 which is problematic for the test suite on
-  # older Ruby versions. Check Ruby the version here and put a maximum
-  # constraint on Rack if necessary.
-  if RUBY_VERSION >= "2.2.2"
-    gem "rack", ">= 2.0.6"
-  else
-    gem "rack", ">= 1.6.11", "< 2.0" # rubocop:disable Bundler/DuplicatedGem
-  end
+  gem "rubocop", "0.80"
 
   platforms :mri do
     gem "byebug"

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,8 +13,6 @@ 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.
 
@@ -22,6 +20,9 @@ The library also provides other features. For example:
 
 See the [Ruby API docs](https://stripe.com/docs/api/ruby#intro).
 
+See [video demonstrations][youtube-playlist] covering how to use the library.
+
+
 ## Installation
 
 You don't need this source code unless you want to modify the gem. If you just
@@ -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,62 @@ 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`)
+
+#### 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 +339,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
 [stripe-mock]: https://github.com/stripe/stripe-mock
 [versioning]: https://stripe.com/docs/api/ruby#versioning
+[youtube-playlist]: https://www.youtube.com/playlist?list=PLy1nL-pvL2M50RmP6ie-gdcSnfOuQCRYk
 
 <!--
 # vim: set tw=79: