recurly 3.4.0 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f39df94147fc041414ea7a4fd71254c61014cdfec4732e7325e327d219069d92
-  data.tar.gz: 48c09a233544b57c4b2948d7d84cdb9eb9c489b3d957da2a2f91aaba3332cb51
+  metadata.gz: 5e07115aaa76b090899e7a8b3fbd473aa4c3d9b53f1a0c2e6610bb48e3cfd2c0
+  data.tar.gz: 0e9dd8516ed793916175fb8e500894925cfe030f8fa6a3b1457420ab3b23a12f
 SHA512:
-  metadata.gz: bf7b86f0522eb6b30a056f3ab85a50589b467098cec88ad52751608cc6d903ec4148fd7d228fb861ada427b985eb6004ffc6fb976790bb2ae390f41013ac8075
-  data.tar.gz: b92224a280cef663942667721dfb5eb95336f5b9c110237c4467f2304e4aa5e8901ebb51c9705406c69eeac2036a04a62a1df08eb60bdfd12f463126c6d55a82
+  metadata.gz: 1b159f6322d33ebdac54a9645c9f791c2bbbc22f42b1b398c4f478b657322f001bfc3275870918e2bca88d599d2409fdf3863a485afd0ee5e2d17c67db012362
+  data.tar.gz: 06ed96e99e5e910accf623edd708d36bfa38d439ee4ec7b7e59cdfb8b13cba09e4061ce827e03e66144823c5cd95df4c2741e9e5dd9ee746611ba4a8ef55e817

data/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.4.0
+current_version = 3.8.0
 parse = (?P<major>\d+)
 	\.(?P<minor>\d+)
 	\.(?P<patch>\d+)
@@ -10,3 +10,7 @@ serialize =
 
 [bumpversion:file:lib/recurly/version.rb]
 
+[bumpversion:file:GETTING_STARTED.md]
+parse = (?P<major>\d+)\.(?P<minor>\d+)
+serialize = {major}.{minor}
+

data/.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+on:
+  release:
+    types:
+      - published
+name: Documentation
+jobs:
+  build:
+    name: Publish
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '2.6'
+
+    - name: Build Library and Docs
+      run: ./scripts/build
+
+    - name: Deploy
+      if: success()
+      uses: crazy-max/ghaction-github-pages@v1
+      with:
+        target_branch: gh-pages
+        build_dir: ./doc
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

data/.travis.yml

@@ -4,6 +4,7 @@ rvm:
   - 2.4
   - 2.5
   - 2.6
+  - 2.7
 bundler_args: --binstubs
 before_install:
   - gem update --system

data/CHANGELOG.md

@@ -1,6 +1,98 @@
-# Change Log
+# Changelog
+
+## [3.8.0](https://github.com/recurly/recurly-client-ruby/tree/HEAD)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.7.0...HEAD)
+
+**Implemented enhancements:**
+
+- Wed Jul  1 02:06:24 UTC 2020 Upgrade API version v2019-10-10 [\#605](https://github.com/recurly/recurly-client-ruby/pull/605) ([douglasmiller](https://github.com/douglasmiller))
+
+**Merged pull requests:**
+
+- Release 3.8.0 [\#606](https://github.com/recurly/recurly-client-ruby/pull/606) ([douglasmiller](https://github.com/douglasmiller))
+
+## [3.7.0](https://github.com/recurly/recurly-client-ruby/tree/3.7.0) (2020-06-30)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.6.0...3.7.0)
+
+**Implemented enhancements:**
+
+- Mon Jun 29 17:01:25 UTC 2020 Upgrade API version v2019-10-10 [\#601](https://github.com/recurly/recurly-client-ruby/pull/601) ([douglasmiller](https://github.com/douglasmiller))
+
+**Fixed bugs:**
+
+- Allow :headers to be included in operations [\#597](https://github.com/recurly/recurly-client-ruby/pull/597) ([douglasmiller](https://github.com/douglasmiller))
+
+**Merged pull requests:**
+
+- Release 3.7.0 [\#602](https://github.com/recurly/recurly-client-ruby/pull/602) ([douglasmiller](https://github.com/douglasmiller))
+- Fix doc link [\#596](https://github.com/recurly/recurly-client-ruby/pull/596) ([bhelx](https://github.com/bhelx))
+
+## [3.6.0](https://github.com/recurly/recurly-client-ruby/tree/3.6.0) (2020-06-01)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.5.0...3.6.0)
+
+**Implemented enhancements:**
+
+- Latest Features [\#592](https://github.com/recurly/recurly-client-ruby/pull/592) ([bhelx](https://github.com/bhelx))
+- Support the programmer passing their own logger [\#590](https://github.com/recurly/recurly-client-ruby/pull/590) ([bhelx](https://github.com/bhelx))
+
+**Merged pull requests:**
+
+- Release 3.6.0 [\#594](https://github.com/recurly/recurly-client-ruby/pull/594) ([bhelx](https://github.com/bhelx))
+- Better format error message [\#593](https://github.com/recurly/recurly-client-ruby/pull/593) ([bhelx](https://github.com/bhelx))
+- Let bump2version manage the getting started doc [\#591](https://github.com/recurly/recurly-client-ruby/pull/591) ([bhelx](https://github.com/bhelx))
+- Document `Pager#first` and `Pager#count` [\#589](https://github.com/recurly/recurly-client-ruby/pull/589) ([bhelx](https://github.com/bhelx))
+- Ensure that path parameters are not empty strings [\#587](https://github.com/recurly/recurly-client-ruby/pull/587) ([douglasmiller](https://github.com/douglasmiller))
+
+## [3.5.0](https://github.com/recurly/recurly-client-ruby/tree/3.5.0) (2020-04-20)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.4.1...3.5.0)
+
+**Implemented enhancements:**
+
+- Tue Apr 14 20:21:21 UTC 2020 Upgrade API version v2019-10-10 [\#585](https://github.com/recurly/recurly-client-ruby/pull/585) ([bhelx](https://github.com/bhelx))
+- Set an Idempotency-Key header, retry GET requests after 5xx errors [\#579](https://github.com/recurly/recurly-client-ruby/pull/579) ([isaachall](https://github.com/isaachall))
+- Adding \#first and \#count methods to Pager [\#560](https://github.com/recurly/recurly-client-ruby/pull/560) ([douglasmiller](https://github.com/douglasmiller))
+
+**Fixed bugs:**
+
+- Fixing the omission of query params [\#581](https://github.com/recurly/recurly-client-ruby/pull/581) ([douglasmiller](https://github.com/douglasmiller))
+
+**Merged pull requests:**
+
+- Release 3.5.0 [\#586](https://github.com/recurly/recurly-client-ruby/pull/586) ([douglasmiller](https://github.com/douglasmiller))
+- Included the to-be released changes in the changelog [\#584](https://github.com/recurly/recurly-client-ruby/pull/584) ([douglasmiller](https://github.com/douglasmiller))
+- Add 2.7 to test matrix [\#582](https://github.com/recurly/recurly-client-ruby/pull/582) ([bhelx](https://github.com/bhelx))
+- Use github pages for docs [\#580](https://github.com/recurly/recurly-client-ruby/pull/580) ([bhelx](https://github.com/bhelx))
+- Add project metadata to the gemspec [\#578](https://github.com/recurly/recurly-client-ruby/pull/578) ([orien](https://github.com/orien))
+- Updating release script to be uniform across all clients [\#577](https://github.com/recurly/recurly-client-ruby/pull/577) ([douglasmiller](https://github.com/douglasmiller))
+- Thu Mar 26 20:41:10 UTC 2020 Upgrade API version v2019-10-10 [\#573](https://github.com/recurly/recurly-client-ruby/pull/573) ([bhelx](https://github.com/bhelx))
+
+## [3.4.1](https://github.com/recurly/recurly-client-ruby/tree/3.4.1) (2020-03-26)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.4.0...3.4.1)
+
+**Merged pull requests:**
+
+- Release 3.4.1 [\#571](https://github.com/recurly/recurly-client-ruby/pull/571) ([bhelx](https://github.com/bhelx))
+- Follow up bug fixes for \#568 [\#570](https://github.com/recurly/recurly-client-ruby/pull/570) ([bhelx](https://github.com/bhelx))
+
+## [3.4.0](https://github.com/recurly/recurly-client-ruby/tree/3.4.0) (2020-03-23)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.3.1...3.4.0)
+
+**Implemented enhancements:**
+
+- Replace Faraday gem with Net::HTTP, add connection pooling & keep-alive, update CA roots [\#568](https://github.com/recurly/recurly-client-ruby/pull/568) ([isaachall](https://github.com/isaachall))
+
+**Merged pull requests:**
+
+- Release 3.4.0 [\#569](https://github.com/recurly/recurly-client-ruby/pull/569) ([bhelx](https://github.com/bhelx))
 
 ## [3.3.1](https://github.com/recurly/recurly-client-ruby/tree/3.3.1) (2020-03-20)
+
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.3.0...3.3.1)
 
 **Merged pull requests:**
@@ -12,6 +104,7 @@
 - Add request for stack trace in issue report [\#558](https://github.com/recurly/recurly-client-ruby/pull/558) ([bhelx](https://github.com/bhelx))
 
 ## [3.3.0](https://github.com/recurly/recurly-client-ruby/tree/3.3.0) (2020-02-20)
+
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.2.2...3.3.0)
 
 **Merged pull requests:**
@@ -22,6 +115,7 @@
 - Latest v2019-10-10 Changes [\#552](https://github.com/recurly/recurly-client-ruby/pull/552) ([bhelx](https://github.com/bhelx))
 
 ## [3.2.2](https://github.com/recurly/recurly-client-ruby/tree/3.2.2) (2020-02-03)
+
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.2.1...3.2.2)
 
 **Merged pull requests:**
@@ -30,6 +124,7 @@
 - Loosen version restriction on faraday [\#549](https://github.com/recurly/recurly-client-ruby/pull/549) ([bhelx](https://github.com/bhelx))
 
 ## [3.2.1](https://github.com/recurly/recurly-client-ruby/tree/3.2.1) (2019-12-10)
+
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.2.0...3.2.1)
 
 **Fixed bugs:**
@@ -37,6 +132,7 @@
 - Convert Array params to CSV strings [\#545](https://github.com/recurly/recurly-client-ruby/pull/545) ([douglasmiller](https://github.com/douglasmiller))
 
 ## [3.2.0](https://github.com/recurly/recurly-client-ruby/tree/3.2.0) (2019-12-03)
+
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.1.3...3.2.0)
 
 **Fixed bugs:**
@@ -50,6 +146,7 @@
 - Allow object attributes through [\#542](https://github.com/recurly/recurly-client-ruby/pull/542) ([bhelx](https://github.com/bhelx))
 
 ## [3.1.3](https://github.com/recurly/recurly-client-ruby/tree/3.1.3) (2019-12-02)
+
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.1.2...3.1.3)
 
 **Fixed bugs:**
@@ -58,6 +155,7 @@
 - Issue 540 error may have transaction [\#541](https://github.com/recurly/recurly-client-ruby/pull/541) ([bhelx](https://github.com/bhelx))
 
 ## [3.1.2](https://github.com/recurly/recurly-client-ruby/tree/3.1.2) (2019-12-02)
+
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.1.1...3.1.2)
 
 **Fixed bugs:**
@@ -65,6 +163,7 @@
 - Skip request property type validation for nil values [\#539](https://github.com/recurly/recurly-client-ruby/pull/539) ([bhelx](https://github.com/bhelx))
 
 ## [3.1.1](https://github.com/recurly/recurly-client-ruby/tree/3.1.1) (2019-11-27)
+
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.1.0...3.1.1)
 
 **Fixed bugs:**
@@ -73,6 +172,7 @@
 - Disable searching ancestors when looking up constants [\#537](https://github.com/recurly/recurly-client-ruby/pull/537) ([douglasmiller](https://github.com/douglasmiller))
 
 ## [3.1.0](https://github.com/recurly/recurly-client-ruby/tree/3.1.0) (2019-11-18)
+
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.0.0...3.1.0)
 
 **Merged pull requests:**
@@ -82,6 +182,7 @@
 - Generated Updates for API version v2019-10-10 [\#528](https://github.com/recurly/recurly-client-ruby/pull/528) ([bhelx](https://github.com/bhelx))
 
 ## [3.0.0](https://github.com/recurly/recurly-client-ruby/tree/3.0.0) (2019-10-09)
+
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.0.0.beta.5...3.0.0)
 
 **Merged pull requests:**
@@ -103,13 +204,14 @@
 - Add CONTRIBUTING.md [\#486](https://github.com/recurly/recurly-client-ruby/pull/486) ([bhelx](https://github.com/bhelx))
 - Bump 3.0.0.beta.6 [\#485](https://github.com/recurly/recurly-client-ruby/pull/485) ([bhelx](https://github.com/bhelx))
 -  Latest v2018-08-09 Changes [\#484](https://github.com/recurly/recurly-client-ruby/pull/484) ([bhelx](https://github.com/bhelx))
-- 3.0.0.beta.5 [\#483](https://github.com/recurly/recurly-client-ruby/pull/483) ([bhelx](https://github.com/bhelx))
 
 ## [3.0.0.beta.5](https://github.com/recurly/recurly-client-ruby/tree/3.0.0.beta.5) (2019-06-28)
+
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.0.0.beta.4...3.0.0.beta.5)
 
 **Merged pull requests:**
 
+- 3.0.0.beta.5 [\#483](https://github.com/recurly/recurly-client-ruby/pull/483) ([bhelx](https://github.com/bhelx))
 - Latest v2018-08-09 Changes [\#482](https://github.com/recurly/recurly-client-ruby/pull/482) ([bhelx](https://github.com/bhelx))
 - no longer need dep scripts [\#476](https://github.com/recurly/recurly-client-ruby/pull/476) ([bhelx](https://github.com/bhelx))
 - Add format script and check in specs [\#474](https://github.com/recurly/recurly-client-ruby/pull/474) ([bhelx](https://github.com/bhelx))
@@ -117,28 +219,20 @@
 - Add strict mode for json deserializer [\#469](https://github.com/recurly/recurly-client-ruby/pull/469) ([bhelx](https://github.com/bhelx))
 
 ## [3.0.0.beta.4](https://github.com/recurly/recurly-client-ruby/tree/3.0.0.beta.4) (2019-04-04)
-[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.0.0.beta.3...3.0.0.beta.4)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.0.0.beta.1...3.0.0.beta.4)
 
 **Merged pull requests:**
 
 - V3 Update v2018-08-09 [\#460](https://github.com/recurly/recurly-client-ruby/pull/460) ([aaron-suarez](https://github.com/aaron-suarez))
 - Small fixes for private beta [\#458](https://github.com/recurly/recurly-client-ruby/pull/458) ([bhelx](https://github.com/bhelx))
 - Use Net-http-persistent for persistent connection [\#408](https://github.com/recurly/recurly-client-ruby/pull/408) ([bhelx](https://github.com/bhelx))
-
-## [3.0.0.beta.3](https://github.com/recurly/recurly-client-ruby/tree/3.0.0.beta.3) (2018-08-27)
-[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.0.0.beta.2...3.0.0.beta.3)
-
-**Merged pull requests:**
-
 - Update to API 2018-06-06 [\#407](https://github.com/recurly/recurly-client-ruby/pull/407) ([bhelx](https://github.com/bhelx))
 - Regenerating the client [\#406](https://github.com/recurly/recurly-client-ruby/pull/406) ([drewish](https://github.com/drewish))
 - V3 Pager can error [\#401](https://github.com/recurly/recurly-client-ruby/pull/401) ([drewish](https://github.com/drewish))
 - \[V3\] Test more versions of ruby [\#397](https://github.com/recurly/recurly-client-ruby/pull/397) ([drewish](https://github.com/drewish))
 - Allow faraday 0.12 for compatibility with oauth2 gem [\#396](https://github.com/recurly/recurly-client-ruby/pull/396) ([drewish](https://github.com/drewish))
 
-## [3.0.0.beta.2](https://github.com/recurly/recurly-client-ruby/tree/3.0.0.beta.2) (2018-07-17)
-[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.0.0.beta.1...3.0.0.beta.2)
-
 
 
-\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/GETTING_STARTED.md

@@ -5,7 +5,7 @@ This repository houses the official ruby client for Recurly's V3 API.
 In your Gemfile, add `recurly` as a dependency.
 
 ```ruby
-gem 'recurly', '~> 3.2'
+gem 'recurly', '~> 3.8'
 ```
 
 > *Note*: We try to follow [semantic versioning](https://semver.org/) and will only apply breaking changes to major versions.
@@ -41,6 +41,27 @@ client = Recurly::Client.new(api_key: API_KEY2)
 sub = client.get_subscription(subscription_id: 'abcd7890')
 ```
 
+## Logging
+
+The client constructor optionally accepts a logger provided by the programmer. The logger you pass should be an instance of ruby stdlib's [Logger](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html)
+or follow the same interface. By default, the client creates a logger to `STDOUT` with level `WARN`.
+
+```ruby
+require 'logger'
+
+# Create a logger to STDOUT
+logger = Logger.new(STDOUT)
+logger.level = Logger::INFO
+
+# You could also use an existing logger
+# If you are using Rails you may want to use your application's logger
+logger = Rails.logger
+
+client = Recurly::Client.new(api_key: API_KEY, logger: logger)
+```
+
+> *SECURITY WARNING*: The log level should never be set to DEBUG in production. This could potentially result in sensitive data in your logging system.
+
 # Operations
 
 The {Recurly::Client} contains every `operation` you can perform on the site as a list of methods. Each method is documented explaining
@@ -109,6 +130,45 @@ end
 `limit` defaults to 20 items per page and can be set from 1 to 200. Choosing a lower limit means more network requests but smaller payloads.
 We recommend keeping the default for most cases but increasing the limit if you are planning on iterating through many pages of items (e.g. all transactions in your site).
 
+## Efficiently Fetch the First or Last Resource
+
+The Pager class implements a first method which allows you to fetch just the first or last resource from the server. On top of being a convenient abstraction, this is implemented efficiently by only asking the server for the 1 item you want.
+
+```ruby
+accounts = client.list_accounts(
+  subscriber: true,
+  order: :desc
+)
+
+last_subscriber = accounts.first
+```
+
+If you want to fetch the last account in this scenario, invert the order from descending `desc` to ascending `asc`:
+
+```ruby
+accounts = client.list_accounts(
+  subscriber: true,
+  order: :asc
+)
+
+first_subscriber = accounts.first
+```
+
+## Counting Resources
+
+The Pager class implements a `count` method which allows you to count the resources the pager would return. It does so by calling the endpoint with `HEAD` and parsing and returning the `Recurly-Total-Records` header. This method respects any filtering parameters you apply to the pager, but the sorting parameters will have no effect.
+
+```ruby
+accounts = client.list_accounts(
+  subscriber: true,
+  begin_time: DateTime.new(2017,1,1)
+)
+
+# Calling count here will return an integer indicating
+# the number of subscribers since 2017
+count = accounts.count
+# => 573
+```
 
 # Creating Resources
 

data/README.md

@@ -7,7 +7,7 @@ This repository houses the official ruby client for Recurly's V3 API.
 
 ## Reference Documentation
 
-Getting Started Guide and reference documentation can be found on [rubydoc.info](https://www.rubydoc.info/github/recurly/recurly-client-ruby/).
+Getting Started Guide and reference documentation can be found on [Github Pages](https://recurly.github.io/recurly-client-ruby/).
 
 ## Contributing
 

data/lib/recurly/client.rb

@@ -2,6 +2,7 @@ require "logger"
 require "erb"
 require "net/https"
 require "base64"
+require "securerandom"
 require_relative "./schema/json_parser"
 require_relative "./schema/file_parser"
 
@@ -14,9 +15,12 @@ module Recurly
     CA_FILE = File.join(File.dirname(__FILE__), "../data/ca-certificates.crt")
     BINARY_TYPES = [
       "application/pdf",
-    ]
+    ].freeze
     JSON_CONTENT_TYPE = "application/json"
     MAX_RETRIES = 3
+    LOG_LEVELS = %i(debug info warn error fatal).freeze
+    BASE36_ALPHABET = (("0".."9").to_a + ("a".."z").to_a).freeze
+    REQUEST_OPTIONS = [:headers].freeze
 
     # Initialize a client. It requires an API key.
     #
@@ -42,29 +46,42 @@ module Recurly
     #   sub = client.get_subscription(subscription_id: 'uuid-abcd7890')
     #
     # @param api_key [String] The private API key
-    # @param site_id [String] The site you wish to be scoped to.
-    # @param subdomain [String] Optional subdomain for the site you wish to be scoped to. Providing this makes all the `site_id` parameters optional.
-    def initialize(api_key:, site_id: nil, subdomain: nil, **options)
+    # @param logger [Logger] A logger to use. Defaults to creating a new STDOUT logger with level WARN.
+    def initialize(api_key:, site_id: nil, subdomain: nil, logger: nil)
       set_site_id(site_id, subdomain)
       set_api_key(api_key)
-      set_options(options)
+
+      if logger.nil?
+        @logger = Logger.new(STDOUT).tap do |l|
+          l.level = Logger::WARN
+        end
+      else
+        unless LOG_LEVELS.all? { |lev| logger.respond_to?(lev) }
+          raise ArgumentError, "You must pass in a logger implementation that responds to the following messages: #{LOG_LEVELS}"
+        end
+        @logger = logger
+      end
+
+      if @logger.level < Logger::INFO
+        msg = <<-MSG
+        The Recurly logger should not be initialized
+        beyond the level INFO. It is currently configured to emit
+        headers and request / response bodies. This has the potential to leak
+        PII and other sensitive information and should never be used in production.
+        MSG
+        log_warn("SECURITY_WARNING", message: msg)
+      end
 
       # execute block with this client if given
       yield(self) if block_given?
     end
 
-    def next_page(pager)
-      path = extract_path(pager.next)
-      request = Net::HTTP::Get.new path
-      set_headers(request)
-      http_response = run_request(request)
-      handle_response! request, http_response
-    end
-
     protected
 
+    # Used by the operations.rb file to interpolate paths
+    attr_reader :site_id
+
     def pager(path, **options)
-      path = scope_by_site(path, **options)
       Pager.new(
         client: self,
         path: path,
@@ -72,9 +89,15 @@ module Recurly
       )
     end
 
+    def head(path, **options)
+      request = Net::HTTP::Head.new build_url(path, options)
+      set_headers(request, options[:headers])
+      http_response = run_request(request, options)
+      handle_response! request, http_response
+    end
+
     def get(path, **options)
-      path = scope_by_site(path, **options)
-      request = Net::HTTP::Get.new path
+      request = Net::HTTP::Get.new build_url(path, options)
       set_headers(request, options[:headers])
       http_response = run_request(request, options)
       handle_response! request, http_response
@@ -82,8 +105,7 @@ module Recurly
 
     def post(path, request_data, request_class, **options)
       request_class.new(request_data).validate!
-      path = scope_by_site(path, **options)
-      request = Net::HTTP::Post.new path
+      request = Net::HTTP::Post.new build_url(path, options)
       request.set_content_type(JSON_CONTENT_TYPE)
       set_headers(request, options[:headers])
       request.body = JSON.dump(request_data)
@@ -92,14 +114,12 @@ module Recurly
     end
 
     def put(path, request_data = nil, request_class = nil, **options)
-      path = scope_by_site(path, **options)
-      request = Net::HTTP::Put.new path
+      request = Net::HTTP::Put.new build_url(path, options)
       request.set_content_type(JSON_CONTENT_TYPE)
       set_headers(request, options[:headers])
       if request_data
         request_class.new(request_data).validate!
         json_body = JSON.dump(request_data)
-        logger.info("PUT BODY #{json_body}")
         request.body = json_body
       end
       http_response = run_request(request, options)
@@ -107,23 +127,14 @@ module Recurly
     end
 
     def delete(path, **options)
-      path = scope_by_site(path, **options)
-      request = Net::HTTP::Delete.new path
+      request = Net::HTTP::Delete.new build_url(path, options)
       set_headers(request, options[:headers])
       http_response = run_request(request, options)
       handle_response! request, http_response
     end
 
-    protected
-
-    # Used by the operations.rb file to interpolate paths
-    attr_reader :site_id
-
     private
 
-    # @return [Logger]
-    attr_reader :logger
-
     @connection_pool = Recurly::ConnectionPool.new
 
     class << self
@@ -139,7 +150,38 @@ module Recurly
 
         begin
           http.start unless http.started?
-          http.request(request)
+          log_attrs = {
+            method: request.method,
+            path: request.path,
+          }
+          if @logger.level < Logger::INFO
+            log_attrs[:request_body] = request.body
+            # No need to log the authorization header
+            headers = request.to_hash.reject { |k, _| k&.downcase == "authorization" }
+            log_attrs[:request_headers] = headers
+          end
+
+          log_info("Request", **log_attrs)
+          start = Time.now
+          response = http.request(request)
+          elapsed = Time.now - start
+
+          # GETs are safe to retry after a server error, requests with an Idempotency-Key will return the prior response
+          if response.kind_of?(Net::HTTPServerError) && request.is_a?(Net::HTTP::Get)
+            retries += 1
+            log_info("Retrying", retries: retries, **log_attrs)
+            start = Time.now
+            response = http.request(request) if retries < MAX_RETRIES
+            elapsed = Time.now - start
+          end
+
+          if @logger.level < Logger::INFO
+            log_attrs[:response_body] = response.body
+            log_attrs[:response_headers] = response.to_hash
+          end
+          log_info("Response", time_ms: (elapsed * 1_000).floor, status: response.code, **log_attrs)
+
+          response
         rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ECONNABORTED,
                Errno::EPIPE, Errno::ETIMEDOUT, Net::OpenTimeout, EOFError, SocketError => ex
           retries += 1
@@ -163,26 +205,37 @@ module Recurly
     end
 
     def set_headers(request, additional_headers = {})
+      # TODO this is undocumented until we finalize it
+      additional_headers.each { |header, v| request[header] = v } if additional_headers
+
       request["Accept"] = "application/vnd.recurly.#{api_version}".chomp # got this method from operations.rb
       request["Authorization"] = "Basic #{Base64.encode64(@api_key)}".chomp
       request["User-Agent"] = "Recurly/#{VERSION}; #{RUBY_DESCRIPTION}"
 
-      # TODO this is undocumented until we finalize it
-      additional_headers.each { |header, v| request[header] = v } if additional_headers
+      unless request.is_a?(Net::HTTP::Get) || request.is_a?(Net::HTTP::Head)
+        request["Idempotency-Key"] ||= generate_idempotency_key
+      end
+    end
+
+    # from https://github.com/rails/rails/blob/6-0-stable/activesupport/lib/active_support/core_ext/securerandom.rb
+    def generate_idempotency_key(n = 16)
+      SecureRandom.random_bytes(n).unpack("C*").map do |byte|
+        idx = byte % 64
+        idx = SecureRandom.random_number(36) if idx >= 36
+        BASE36_ALPHABET[idx]
+      end.join
     end
 
     def set_http_options(http, options)
       http.open_timeout = options[:open_timeout] || 20
       http.read_timeout = options[:read_timeout] || 60
-
-      http.set_debug_output(logger) if @log_level <= Logger::INFO && !http.started?
     end
 
     def handle_response!(request, http_response)
       response = HTTP::Response.new(http_response, request)
       raise_api_error!(http_response, response) unless http_response.kind_of?(Net::HTTPSuccess)
       resource = if response.body
-          if http_response.content_type.include?(JSON_CONTENT_TYPE)
+          if http_response.content_type&.include?(JSON_CONTENT_TYPE)
             JSONParser.parse(self, response.body)
           elsif BINARY_TYPES.include?(http_response.content_type)
             FileParser.parse(response.body)
@@ -216,15 +269,15 @@ module Recurly
 
     def read_headers(response)
       if !@_ignore_deprecation_warning && response.headers["Recurly-Deprecated"]&.upcase == "TRUE"
-        puts "[recurly-client-ruby] WARNING: Your current API version \"#{api_version}\" is deprecated and will be sunset on #{response.headers["Recurly-Sunset-Date"]}"
+        log_warn("DEPRECTATION WARNING", message: "Your current API version \"#{api_version}\" is deprecated and will be sunset on #{response.headers["Recurly-Sunset-Date"]}")
       end
       response
     end
 
-    def interpolate_path(path, **options)
+    def validate_path_parameters!(**options)
+      # Check to see that we are passing the correct data types
+      # This prevents a confusing error if the user passes in a non-primitive by mistake
       options.each do |k, v|
-        # Check to see that we are passing the correct data types
-        # This prevents a confusing error if the user passes in a non-primitive by mistake
         unless [String, Symbol, Integer, Float].include?(v.class)
           message = "We cannot build the url with the given argument #{k}=#{v.inspect}."
           if k =~ /_id$/
@@ -232,6 +285,17 @@ module Recurly
           end
           raise ArgumentError, message
         end
+      end
+      # Check to make sure that parameters are not empty string values
+      empty_strings = options.select { |_, v| v.is_a?(String) && v.strip.empty? }
+      if empty_strings.any?
+        raise ArgumentError, "#{empty_strings.keys.join(", ")} cannot be an empty string"
+      end
+    end
+
+    def interpolate_path(path, **options)
+      validate_path_parameters!(options)
+      options.each do |k, v|
         # We need to encode the values for the url
         options[k] = ERB::Util.url_encode(v.to_s)
       end
@@ -251,24 +315,34 @@ module Recurly
       @api_key = api_key
     end
 
-    def scope_by_site(path, **options)
-      if site = site_id || options[:site_id]
-        "/sites/#{site}#{path}"
+    def build_url(path, options)
+      path = scope_by_site(path, options)
+      query_params = options.reject { |k, _| REQUEST_OPTIONS.include?(k.to_sym) }
+      if query_params.any?
+        "#{path}?#{URI.encode_www_form(query_params)}"
       else
         path
       end
     end
 
-    # Returns just the path and parameters so we can safely reuse the connection
-    def extract_path(uri_or_path)
-      uri = URI(uri_or_path)
-      uri.kind_of?(URI::HTTP) ? uri.request_uri : uri_or_path
+    def scope_by_site(path, **options)
+      if site = site_id || options[:site_id]
+        # Ensure that we are only including the site_id once because the Pager operations
+        # will use the cursor returned from the API which may already have these components
+        path.start_with?("/sites/#{site}") ? path : "/sites/#{site}#{path}"
+      else
+        path
+      end
     end
 
-    def set_options(options)
-      @log_level = options[:log_level] || Logger::WARN
-      @logger = Logger.new(STDOUT)
-      @logger.level = @log_level
+    # Define a private `log_<level>` method for each log level
+    LOG_LEVELS.each do |level|
+      define_method "log_#{level}" do |tag, **attrs|
+        @logger.send(level, "Recurly") do
+          msg = attrs.each_pair.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+          "[#{tag}] #{msg}"
+        end
+      end
     end
   end
 end