recurly 3.16.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7b4df1917c4b15c1d01a13889c926f0c262c2ca1d5ccea2d74dabd19f9a8744
-  data.tar.gz: 33dbffde9c280aa495676f348a103a18d40c2627b7e98f7876cdca1704e49d45
+  metadata.gz: 363aee14af2df360e4440e215556f60535e2a5293c413b37204371e46dba7f30
+  data.tar.gz: 83bae016d349769eebe8206f4ba8e02d2cd072c6d1fccee519054fc433bbde62
 SHA512:
-  metadata.gz: 549b263ed42946ab85c5efa475a66c11c35d4a0ea4098f814a8096ffb6cf4ad2bb413d1ee7ae5603fea4027cbe3fcc9c7d5bd4d358203f142fa47964a3a21b99
-  data.tar.gz: ec7d592254799f676bdc0ca6c95e4b173c35a3535200d5f76fbeb4609600ac6639d194b8705d942e6e184b6b68fce400ce697bc0398cbfbe40bfe2ea7b4a2b15
+  metadata.gz: 99d4ee6a951df8b4714c56c31c35b0c6ae27f29c7dc77e22a6ddd57dd743174980a280d65013350fa89c18b14523a885c56e3214ea05bdf6388c5876b3d28ec1
+  data.tar.gz: 96584a101083b1d7b3678bed505fd1e91bf9c1747bc9a7834467c9e7d6fb2c4f1f18ce17af4f4ff366fe5f0c32f39996f87566f7ea6c15f7c62172fe2b6d3047

data/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.16.0
+current_version = 4.0.1
 parse = (?P<major>\d+)
 	\.(?P<minor>\d+)
 	\.(?P<patch>\d+)

data/.github_changelog_generator

@@ -1,8 +1,8 @@
 user=recurly
 project=recurly-client-ruby
 unreleased=false
-exclude-labels=question,bug?,duplicate,V2
-exclude-tags-regex=^[^3]+\..*
+exclude-labels=internal,question,bug?,duplicate,V2
+exclude-tags-regex=^[^34]+\..*
 issues-wo-labels=false
 verbose=false
 since-tag=3.0.0.beta.1

data/.travis.yml

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

data/CHANGELOG.md

@@ -1,17 +1,147 @@
 # Changelog
 
-## [3.16.0](https://github.com/recurly/recurly-client-ruby/tree/HEAD)
+## [4.0.1](https://github.com/recurly/recurly-client-ruby/tree/4.0.1) (2021-03-19)
 
-[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.15.0...HEAD)
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/4.0.0...4.0.1)
+
+**Merged pull requests:**
+
+- Release 4.0.1 [\#682](https://github.com/recurly/recurly-client-ruby/pull/682) ([douglasmiller](https://github.com/douglasmiller))
+- More ruby 3.0 [\#680](https://github.com/recurly/recurly-client-ruby/pull/680) ([douglasmiller](https://github.com/douglasmiller))
+- Additional fix for ruby 3.x [\#679](https://github.com/recurly/recurly-client-ruby/pull/679) ([douglasmiller](https://github.com/douglasmiller))
+- Generated Latest Changes for v2021-02-25 [\#678](https://github.com/recurly/recurly-client-ruby/pull/678) ([recurly-integrations](https://github.com/recurly-integrations))
+- Sync updates not ported from 3.x client [\#671](https://github.com/recurly/recurly-client-ruby/pull/671) ([douglasmiller](https://github.com/douglasmiller))
+
+## [4.0.0](https://github.com/recurly/recurly-client-ruby/tree/4.0.0) (2021-03-01)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.18.1...4.0.0)
+
+# Major Version Release
+
+The 4.x major version of the client pairs with the `v2021-02-25` API version. This version of the client and the API contain breaking changes that should be considered before upgrading your integration.
+
+## Breaking Changes in the API
+All changes to the core API are documented in the [Developer Portal changelog](https://developers.recurly.com/api/changelog.html#v2021-02-25---current-ga-version)
+
+## Breaking Changes in Client
+
+- Remove `site_id` and `subdomain` from client initializer.  [#624]
+- Remove `set_site_id` method from client.  [#627]
+- Classify unexpected error responses from Recurly API via an HTTP status code mapping provided in `Recurly::Errors::ERROR_MAP`.  [#616]
+- Remove `NetworkError` class. All error classes now extend the `APIError`. This means that the order of multiple rescue blocks will need to be re-considered.  [#616]
+
+    ### 3.x
+    
+    ```ruby
+    rescue Recurly::Errors::ValidationError => ex
+      # catch a validation error
+    rescue Recurly::Errors::APIError => ex
+      # catch a generic api error
+    rescue Recurly::Errors::TimeoutError => ex
+      # catch a specific network error
+    ```
+    
+    ### 4.x
+    
+    ```ruby
+    rescue Recurly::Errors::ValidationError => ex
+      # catch a validation error
+    rescue Recurly::Errors::TimeoutError => ex
+      # catch a specific network error
+    rescue Recurly::Errors::APIError => ex
+      # catch a generic api error
+    ```
+
+- Rename `InvalidResponseError` to `InvalidContentTypeError`.  [#616]
+- Rename `UnavailableError` to `ServiceUnavailableError`.  [#616]
+- Reorganize top-level keys of the optional parameters hash to improve clarity and create space for additional options.  [#619]
+
+    ### 3.x
+    
+    ```ruby
+    options = {
+      limit: 200,
+      headers: {
+        'Accept-Language' => 'fr'
+      }
+    }
+    accounts = @client.list_accounts(options)
+    ```
+    
+    ### 4.x
+    
+    ```ruby
+    options = {
+      params: {
+          limit: 200
+      }
+      headers: {
+        'Accept-Language' => 'fr'
+      }
+    }
+    accounts = @client.list_accounts(options)
+    ```
 
 **Implemented enhancements:**
 
-- Latest Changes for 2019-10-10 \(tax\_identifier / tax\_identifier\_type\) [\#654](https://github.com/recurly/recurly-client-ruby/pull/654) ([douglasmiller](https://github.com/douglasmiller))
-- Latest Changes for 2019-10-10 [\#651](https://github.com/recurly/recurly-client-ruby/pull/651) ([douglasmiller](https://github.com/douglasmiller))
+- Remove site\_id and subdomain from client initializer [\#624](https://github.com/recurly/recurly-client-ruby/pull/624) ([joannasese](https://github.com/joannasese))
+
+**Fixed bugs:**
+
+- Every method is returning wrong number of arguments [\#664](https://github.com/recurly/recurly-client-ruby/issues/664)
+
+**Merged pull requests:**
+
+- Release 4.0.0 [\#669](https://github.com/recurly/recurly-client-ruby/pull/669) ([douglasmiller](https://github.com/douglasmiller))
+- Updating changelog script and changelog generator config for 4.x release [\#663](https://github.com/recurly/recurly-client-ruby/pull/663) ([douglasmiller](https://github.com/douglasmiller))
+- Removing unused method 'set\_site\_id' [\#627](https://github.com/recurly/recurly-client-ruby/pull/627) ([douglasmiller](https://github.com/douglasmiller))
+- Updating 4.x client to expect query string params as \['params'\] [\#619](https://github.com/recurly/recurly-client-ruby/pull/619) ([douglasmiller](https://github.com/douglasmiller))
+- Updating error mapping based on status code [\#616](https://github.com/recurly/recurly-client-ruby/pull/616) ([douglasmiller](https://github.com/douglasmiller))
+
+## [3.18.1](https://github.com/recurly/recurly-client-ruby/tree/3.18.1) (2021-02-22)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.18.0...3.18.1)
 
 **Fixed bugs:**
 
-- Refund API V2 Error Details [\#652](https://github.com/recurly/recurly-client-ruby/issues/652)
+- Fixing issues with ruby 3.0 [\#665](https://github.com/recurly/recurly-client-ruby/pull/665) ([douglasmiller](https://github.com/douglasmiller))
+
+**Merged pull requests:**
+
+- Release 3.18.1 [\#666](https://github.com/recurly/recurly-client-ruby/pull/666) ([douglasmiller](https://github.com/douglasmiller))
+
+## [3.18.0](https://github.com/recurly/recurly-client-ruby/tree/3.18.0) (2021-01-22)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.17.0...3.18.0)
+
+**Implemented enhancements:**
+
+- Latest Changes for 2019-10-10 [\#660](https://github.com/recurly/recurly-client-ruby/pull/660) ([douglasmiller](https://github.com/douglasmiller))
+
+**Merged pull requests:**
+
+- Release 3.18.0 [\#661](https://github.com/recurly/recurly-client-ruby/pull/661) ([douglasmiller](https://github.com/douglasmiller))
+
+## [3.17.0](https://github.com/recurly/recurly-client-ruby/tree/3.17.0) (2020-12-08)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.16.0...3.17.0)
+
+**Implemented enhancements:**
+
+- Latest Changes for 2019-10-10 [\#657](https://github.com/recurly/recurly-client-ruby/pull/657) ([douglasmiller](https://github.com/douglasmiller))
+
+**Merged pull requests:**
+
+- Release 3.17.0 [\#658](https://github.com/recurly/recurly-client-ruby/pull/658) ([douglasmiller](https://github.com/douglasmiller))
+
+## [3.16.0](https://github.com/recurly/recurly-client-ruby/tree/3.16.0) (2020-11-24)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.15.0...3.16.0)
+
+**Implemented enhancements:**
+
+- Latest Changes for 2019-10-10 \(tax\_identifier / tax\_identifier\_type\) [\#654](https://github.com/recurly/recurly-client-ruby/pull/654) ([douglasmiller](https://github.com/douglasmiller))
+- Latest Changes for 2019-10-10 [\#651](https://github.com/recurly/recurly-client-ruby/pull/651) ([douglasmiller](https://github.com/douglasmiller))
 
 **Merged pull requests:**
 
@@ -324,7 +454,7 @@
 
 ## [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.1...3.0.0.beta.4)
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.0.0.beta.3...3.0.0.beta.4)
 
 **Merged pull requests:**
 
@@ -337,6 +467,14 @@
 - \[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.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)
+
+## [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 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.16'
+gem 'recurly', '~> 4.0'
 ```
 
 > *Note*: We try to follow [semantic versioning](https://semver.org/) and will only apply breaking changes to major versions.
@@ -106,17 +106,19 @@ plans.each_page.each_with_index do |data, page_num|
 end
 ```
 
-Pagination endpoints take a number of options to sort and filter the results. They can be passed in as keyword arguments.
+Pagination endpoints take a number of options to sort and filter the results. They can be passed in as a hash provided by the `:params` keyword argument.
 The names, types, and descriptions of these arguments are listed in the rubydocs for each method:
 
 ```ruby
 options = {
-  limit: 200, # number of items per page
-  state: :active, # only active plans
-  sort: :updated_at,
-  order: :asc,
-  begin_time: DateTime.new(2017,1,1), # January 1st 2017,
-  end_time: DateTime.now
+  params: {
+    limit: 200, # number of items per page
+    state: :active, # only active plans
+    sort: :updated_at,
+    order: :asc,
+    begin_time: DateTime.new(2017,1,1), # January 1st 2017,
+    end_time: DateTime.now
+  }
 }
 
 plans = client.list_plans(**options)
@@ -200,12 +202,11 @@ plan = client.create_plan(body: plan_data)
 
 # Error Handling
 
-This library currently throws 2 types of exceptions. {Recurly::Errors::APIError} and {Recurly::Errors::NetworkError}. See these 2 files for the types of exceptions you can catch:
+All errors thrown by this library are based off of the `Recurly::Errors::APIError`. There 
 
-1. [API Errors](./lib/recurly/errors/api_errors.rb)
-2. [Network Errors](./lib/recurly/errors/network_errors.rb)
+This library throws one main type of exception, `Recurly::Errors::APIError`. There exists an additional hierarchy of errors to facilitate the process of rescuing various classes of errors. More detail can be found in the [Api Errors Module](./lib/recurly/errors/api_errors.rb).
 
-You will normally be working with {Recurly::Errors::APIError}. You can catch specific or generic versions of these exceptions. Example:
+You can catch specific or generic versions of these exceptions. Example:
 
 ```ruby
 begin
@@ -233,15 +234,17 @@ rescue Recurly::Errors::ValidationError => ex
   #=> #<Recurly::Error:0x007fbbdf8a32c8 @attributes={:type=>"validation", :message=>"Code 'iexistalready' already exists", :params=>[{"param"=>"code", "message"=>"'iexistalready' already exists"}]}>
   puts ex.status_code
   #=> 422
+rescue Recurly::Errors::TimeoutError => ex
+  # catch a specific server error
+rescue Recurly::Errors::ServerError => ex
+  # catch a generic server error
 rescue Recurly::Errors::APIError => ex
   # catch a generic api error
-rescue Recurly::Errors::TimeoutError => ex
-  # catch a specific network error
-rescue Recurly::Errors::NetworkError => ex
-  # catch a generic network error
 end
 ```
 
+`Recurly::Errors::APIError` instances provide access to the response via the `#get_response` method.
+
 # HTTP Metadata
 
 Sometimes you might want to get some additional information about the underlying HTTP request and response. Instead of
@@ -266,7 +269,7 @@ response = @client.remove_line_item(
   line_item_id: "a959576b2b10b012"
 ).get_response
 ```
-And it can be captured on exceptions through the {Recurly::ApiError} object:
+And it can be captured on exceptions through the {Recurly::APIError} object:
 
 ```ruby
 begin

data/lib/recurly/client.rb

@@ -20,7 +20,14 @@ module Recurly
     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
+    ALLOWED_OPTIONS = [
+      :site_id,
+      :open_timeout,
+      :read_timeout,
+      :body,
+      :params,
+      :headers,
+    ].freeze
 
     # Initialize a client. It requires an API key.
     #
@@ -47,8 +54,7 @@ module Recurly
     #
     # @param api_key [String] The private API key
     # @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)
+    def initialize(api_key:, logger: nil)
       set_api_key(api_key)
 
       if logger.nil?
@@ -90,6 +96,7 @@ module Recurly
     end
 
     def head(path, **options)
+      validate_options!(**options)
       request = Net::HTTP::Head.new build_url(path, options)
       set_headers(request, options[:headers])
       http_response = run_request(request, options)
@@ -97,6 +104,7 @@ module Recurly
     end
 
     def get(path, **options)
+      validate_options!(**options)
       request = Net::HTTP::Get.new build_url(path, options)
       set_headers(request, options[:headers])
       http_response = run_request(request, options)
@@ -104,6 +112,7 @@ module Recurly
     end
 
     def post(path, request_data, request_class, **options)
+      validate_options!(**options)
       request_class.new(request_data).validate!
       request = Net::HTTP::Post.new build_url(path, options)
       request.set_content_type(JSON_CONTENT_TYPE)
@@ -114,6 +123,7 @@ module Recurly
     end
 
     def put(path, request_data = nil, request_class = nil, **options)
+      validate_options!(**options)
       request = Net::HTTP::Put.new build_url(path, options)
       request.set_content_type(JSON_CONTENT_TYPE)
       set_headers(request, options[:headers])
@@ -127,6 +137,7 @@ module Recurly
     end
 
     def delete(path, **options)
+      validate_options!(**options)
       request = Net::HTTP::Delete.new build_url(path, options)
       set_headers(request, options[:headers])
       http_response = run_request(request, options)
@@ -240,7 +251,7 @@ module Recurly
           elsif BINARY_TYPES.include?(http_response.content_type)
             FileParser.parse(response.body)
           else
-            raise Recurly::Errors::InvalidResponseError, "Unexpected content type: #{http_response.content_type}"
+            raise Recurly::Errors::InvalidContentTypeError, "Unexpected content type: #{http_response.content_type}"
           end
         else
           Resources::Empty.new
@@ -255,10 +266,10 @@ module Recurly
         error = JSONParser.parse(self, response.body)
         begin
           error_class = Errors::APIError.error_class(error.type)
-          raise error_class.new(response, error)
+          raise error_class.new(error.message, response, error)
         rescue NameError
           error_class = Errors::APIError.from_response(http_response)
-          raise error_class.new(response, error)
+          raise error_class.new("Unknown Error", response, error)
         end
       end
 
@@ -266,7 +277,7 @@ module Recurly
 
       if error_class <= Recurly::Errors::APIError
         error = Recurly::Resources::Error.new(message: "#{http_response.code}: #{http_response.message}")
-        raise error_class.new(response, error)
+        raise error_class.new(error.message, response, error)
       else
         raise error_class, "#{http_response.code}: #{http_response.message}"
       end
@@ -279,6 +290,17 @@ module Recurly
       response
     end
 
+    def validate_options!(**options)
+      invalid_options = options.keys.reject do |k|
+        ALLOWED_OPTIONS.include?(k)
+      end
+      if invalid_options.any?
+        joinedKeys = invalid_options.join(", ")
+        joinedOptions = ALLOWED_OPTIONS.join(", ")
+        raise ArgumentError, "Invalid options: '#{joinedKeys}'. Allowed options: '#{joinedOptions}'"
+      end
+    end
+
     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
@@ -299,7 +321,7 @@ module Recurly
     end
 
     def interpolate_path(path, **options)
-      validate_path_parameters!(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)
@@ -308,21 +330,13 @@ module Recurly
       path % options
     end
 
-    def set_site_id(site_id, subdomain)
-      if site_id
-        @site_id = site_id
-      elsif subdomain
-        @site_id = "subdomain-#{subdomain}"
-      end
-    end
-
     def set_api_key(api_key)
       @api_key = api_key
     end
 
     def build_url(path, options)
       path = scope_by_site(path, options)
-      query_params = options.reject { |k, _| REQUEST_OPTIONS.include?(k.to_sym) }
+      query_params = map_array_params(options.fetch(:params, {}))
       if query_params.any?
         "#{path}?#{URI.encode_www_form(query_params)}"
       else
@@ -330,7 +344,16 @@ module Recurly
       end
     end
 
-    def scope_by_site(path, **options)
+    # Converts array parameters to CSV strings to maintain consistency with
+    # how the server expects the request to be formatted while providing the
+    # developer with an array type to maintain developer happiness!
+    def map_array_params(params)
+      params.map do |key, param|
+        [key, param.is_a?(Array) ? param.join(",") : param]
+      end.to_h
+    end
+
+    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