recurly 3.0.0.beta.5 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 3a83d4657995fd0ff223c206cec0f070cd2444d6
-  data.tar.gz: 30cd8091362db149ca7c6b58eda4bc0e28909362
+SHA256:
+  metadata.gz: 22a128d84f15a6887446e5f7791f3d6b91d67cec94641198ff3a4317c73a17a5
+  data.tar.gz: 71ac80f190a092f50cc8e9b2f7d8ab9eb5a91aa0528cacccbce642e488ef9616
 SHA512:
-  metadata.gz: f4e1d7f40eddeec2548d7725b00a23753ce9c89101395a15bb33039ff8e4fc76366c6fab7d77739ba78a3d8ae5106bc42e0a86cd55b6f6b58d9ef8a0cbbcac3e
-  data.tar.gz: 7a009fc1f8447ae303d17cf4040fbb3b7e0ccbf391814479a9003342a06e059febbe4d8fe243c082a74a7c63da7afb57a5ad73b6d03cb067174b63dff2f2319e
+  metadata.gz: ba861fa4d8f40dcc52e3cd4f2b7484aeaf90d5364deaccdf4e9e5894ee15cfdf98c3f05042d7916dd492278244a986fdfb547837214354eab3fc6c1678eb168b
+  data.tar.gz: bf1733bd81f4250afa91841f1e352bb884378c4edfb47bab62857c18d0ba40c74d7e1fdebbdacfc2a4289c31a895c675427d181688840e71a7da5e14a1997b01

data/.bumpversion.cfg

@@ -0,0 +1,12 @@
+[bumpversion]
+current_version = 3.0.0
+parse = (?P<major>\d+)
+	\.(?P<minor>\d+)
+	\.(?P<patch>\d+)
+serialize = 
+	{major}.{minor}.{patch}
+
+[bumpversion:part:build]
+
+[bumpversion:file:lib/recurly/version.rb]
+

data/.travis.yml

@@ -6,7 +6,7 @@ rvm:
   - 2.6
 bundler_args: --binstubs
 before_install:
-  - gem uninstall -v '>= 2' -i $(rvm gemdir)@global -ax bundler || true
-  - gem install bundler -v '< 2'
+  - gem update --system
+  - gem install bundler
 script:
   - ./scripts/test

data/.yardopts

@@ -0,0 +1,3 @@
+--readme GETTING_STARTED.md
+-
+GETTING_STARTED.md

data/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing Guide
+
+👍🎉 First off, thanks for taking the time to contribute! 🎉👍
+
+Filing an Issue or a Pull Request is often the best way to address a problem with this library;
+however, we may not get to these right away. Although we try to be quick, our primary, daily focus is
+writing code. If you want a timely response (especially if you have an emergency), we recommend
+you contact our [official support team](https://support.recurly.com/).
+
+#### Table Of Contents
+
+* [I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question)
+* [I think something is wrong with this library](#i-think-something-is-wrong-with-this-library)
+* [I know what's wrong and I want to submit a code change](#i-know-whats-wrong-and-i-want-to-submit-a-code-change)
+  * [Development Dependencies](#development-dependencies)
+  * [Building and Testing](#building-and-testing)
+  * [Formatting Code](#formatting-code)
+  * [Generated Code](#generated-code)
+
+
+## I don't want to read this whole thing I just have a question!!!
+
+The best way to get a question answered is through our [official support channel](https://support.recurly.com/). If you
+have a specific question related to this library and cannot find an answer, feel free to post an issue with the question.
+
+## I think something is wrong with this library
+
+Are you getting an exception or seeing some unexpected behavior from the library? An issue is the way to go.
+Submit an issue and make sure you provide as much detail as possible. Some things you'll want to include:
+
+* Your dependency versions (client version, language version, OS, etc)
+* A stack trace if available
+* A [Minimal, Reproducible Example](https://stackoverflow.com/help/minimal-reproducible-example)
+
+The more information you give us, the quicker and easier the response will be. Keep in mind that issues should be scoped
+to a problem in this library and we may often redirect you to our official support for problems originating from
+upstream systems.
+
+## I know what's wrong and I want to submit a code change
+
+So, you are sure you want to submit a change to the code? We appreciate the help!
+Before you do, consider opening a discussion in the form of an issue. This accomplish a few things:
+
+1. We can give you advice to implement the change
+2. We can give you an idea of our openness to the change
+
+**Note**: Sending code without a discussion is *always* fine. Discussion on the PR is often easier anyway. Just understand that we may
+not accept the code if we don't think it's best for everyone using the library.
+
+The rest of this section describes what you'll need to know.
+
+### Development Dependencies
+
+You're going to first need a supported version of the language toolchain. The best way to find which versions are supported are by checking
+the [Travis File](.travis.yml) which is used to run our tests. We try to test against every supported version of the language. The [README](README.md)
+may also have something to say about supported dependencies.
+
+### Building and Testing
+
+All of our client libraries contain a `scripts` folder which houses a set of bash scripts for doing common
+development tasks. These scripts follow the same naming conventions so this can act as a kind of "Bash API"
+for manipulating the libraries.
+
+**Note**: If you are on a system without bash (such as some Windows systems), you should find the scripts only consist of a
+few commands which can easily be run in your terminal or editor directly.
+
+Start by running the `build` script to setup deps, compile (if applicable), build docs, etc:
+
+```bash
+./scripts/build
+```
+
+Use the `test` script to run the tests:
+
+```bash
+./scripts/test
+```
+
+Make sure the tests pass locally before submitting your change.
+
+### Formatting Code
+
+The PR (and often the tests) will fail if you have not properly formatted the code. Instead of having a style-guide, we've provided
+an auto-formatter. To use it, run the `format` script:
+
+```bash
+./scripts/format
+```
+
+### Generated Code
+
+Some files in this codebase are generated by a non-public, proprietary program. Because they are regularly generated and updated as the
+API and docs change, we won't accept any PRs that modify these files. Each of these files has a disclaimer on the top saying that they cannot
+be edited by hand. By convention, they relate to things that are specific to the Recurly API that may change. For example:
+
+* Response Schemas (Resources)
+* Request Schemas (Requests)
+* API endpoints (Operations)
+* Errors
+
+If you feel like you need one of these to change, please file an issue and we can discuss getting the change upstreamed.
+

data/GETTING_STARTED.md

@@ -0,0 +1,266 @@
+# Recurly
+
+## Getting Started
+
+### Installing
+
+In your Gemfile, add `recurly` as a dependency.
+
+```ruby
+gem 'recurly', '~> 3.0'
+```
+
+> *Note*: We try to follow [semantic versioning](https://semver.org/) and will only apply breaking changes to major versions.
+
+### Creating a client
+
+Client instances are now explicitly created and referenced as opposed to V2's use of global, statically
+initialized clients.
+
+This makes multithreaded environments simpler and provides one location where every
+operation can be found (rather than having them spread out among classes).
+
+`Recurly::Client#new` initializes a new client. It only requires an API key which can be obtained on
+the [API Credentials Page](https://app.recurly.com/go/integrations/api_keys).
+
+```ruby
+API_KEY = '83749879bbde395b5fe0cc1a5abf8e5'
+client = Recurly::Client.new(api_key: API_KEY)
+sub = client.get_subscription(subscription_id: 'abcd123456')
+```
+
+You can also pass the initializer a block. This will give you a client scoped for just that block:
+
+```ruby
+Recurly::Client.new(api_key: API_KEY) do |client|
+  sub = client.get_subscription(subscription_id: 'abcd123456')
+end
+```
+
+If you plan on using the client for more than one site, you should initialize a new client for each site.
+
+```ruby
+client = Recurly::Client.new(api_key: API_KEY1) 
+sub = client.get_subscription(subscription_id: 'abcd123456')
+
+# you should create a new client to connect to another site
+client = Recurly::Client.new(api_key: API_KEY2) 
+sub = client.get_subscription(subscription_id: 'abcd7890')
+```
+
+### Operations
+
+The {Recurly::Client} contains every `operation` you can perform on the site as a list of methods. Each method is documented explaining
+the types and descriptions for each input and return type. You can view all available operations by looking at the `Instance Methods Summary` list
+on the {Recurly::Client} documentation page. Clicking a method will give you detailed information about its inputs and returns. Take the `create_account`
+operation as an example: {Recurly::Client#create_account}.
+
+### Pagination
+
+Pagination is done by the class {Recurly::Pager}. All `list_*` methods on the client return an instance of this class.
+The pager has an `each` method which accepts a block for each object in the entire list. Each page is fetched automatically
+for you presenting the elements as a single enumerable.
+
+```ruby
+plans = client.list_plans()
+plans.each do |plan|
+  puts "Plan: #{plan.id}"
+end
+```
+
+You may also paginate in chunks with `each_page`.
+
+```ruby
+plans = client.list_plans()
+plans.each_page do |data|
+  data.each do |plan|
+    puts "Plan: #{plan.id}"
+  end
+end
+```
+
+Both {Pager#each} and {Pager#each_page} return Enumerators if a block is not given. This allows you to use other Enumerator methods
+such as `map` or `each_with_index`.
+
+```ruby
+plans = client.list_plans()
+plans.each_page.each_with_index do |data, page_num|
+  puts "Page Number #{page_num}"
+  data.each do |plan|
+    puts "Plan: #{plan.id}"
+  end
+end
+```
+
+Pagination endpoints take a number of options to sort and filter the results. They can be passed in as keyword arguments.
+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
+}
+
+plans = client.list_plans(**options)
+plans.each do |plan|
+  puts "Plan: #{plan.id}"
+end
+```
+
+**A note on `limit`**:
+
+`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).
+
+
+### Creating Resources
+
+Currently, resources are created by passing in a `body` keyword argument in the form of a `Hash`.
+This Hash must follow the schema of the documented request type. For example, the `create_plan` operation
+takes a request of type {Recurly::Requests::PlanCreate}. Failing to conform to this schema will result in an argument
+error.
+
+```ruby
+require 'securerandom'
+
+code = SecureRandom.uuid
+plan_data = {
+  code: code,
+  interval_length: 1,
+  interval_unit: 'months',
+  name: code,
+  currencies: [
+    {
+      currency: 'USD',
+      setup_fee: 800,
+      unit_amount: 10
+    }
+  ]
+}
+
+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:
+
+1. [API Errors](./lib/recurly/errors/api_errors.rb)
+2. [Network Errors](./lib/recurly/errors/network_errors.rb)
+
+You will normally be working with {Recurly::Errors::APIError}. You can catch specific or generic versions of these exceptions. Example:
+
+```ruby
+begin
+  client = Recurly::Client.new(api_key: API_KEY)
+  code = "iexistalready"
+  plan_data = {
+    code: code,
+    interval_length: 1,
+    interval_unit: 'months',
+    name: code,
+    currencies: [
+      {
+        currency: 'USD',
+        setup_fee: 800,
+        unit_amount: 10
+      }
+    ]
+  }
+
+  plan = client.create_plan(body: plan_data)
+rescue Recurly::Errors::ValidationError => ex
+  puts ex.inspect
+  #=> #<Recurly::ValidationError: Recurly::ValidationError: Code 'iexistalready' already exists>
+  puts ex.recurly_error.inspect
+  #=> #<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::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
+```
+
+### HTTP Metadata
+
+Sometimes you might want to get some additional information about the underlying HTTP request and response. Instead of
+returning this information directly and forcing the programmer to unwrap it, we inject this metadata into the top level
+resource that was returned. You can access the {Recurly::HTTP::Response} by calling `#get_response` on any {Recurly::Resource}.
+
+**Warning**: Do not log or render whole requests or responses as they may contain PII or sensitive data.
+
+```ruby
+account = @client.get_account(account_id: "code-benjamin")
+response = account.get_response
+response.rate_limit_remaining #=> 1985
+response.request_id #=> "0av50sm5l2n2gkf88ehg"
+response.request.path #=> "/sites/subdomain-mysite/accounts/code-benjamin"
+response.request.body #=> None
+```
+
+This also works on {Recurly::Resources::Empty} responses:
+
+```ruby
+response = @client.remove_line_item(
+  line_item_id: "a959576b2b10b012"
+).get_response
+```
+And it can be captured on exceptions through the {Recurly::ApiError} object:
+
+```ruby
+begin
+  account = client.get_account(account_id: "code-benjamin")
+rescue Recurly::Errors::NotFoundError => e
+  response = e.get_response()
+  puts "Give this request id to Recurly Support: #{response.request_id}"
+end
+```
+
+### Webhooks
+
+Recurly can send webhooks to any publicly accessible server.
+When an event in Recurly triggers a webhook (e.g., an account is opened),
+Recurly will attempt to send this notification to the endpoint(s) you specify.
+You can specify up to 10 endpoints through the application. All notifications will
+be sent to all configured endpoints for your site. 
+
+See our [product docs](https://docs.recurly.com/docs/webhooks) to learn more about webhooks
+and see our [dev docs](https://dev.recurly.com/page/webhooks) to learn about what payloads
+are available.
+
+Although our API is now JSON, our webhook payloads are still formatted as XML for the time being.
+This library is not yet responsible for handling webhooks. If you do need webhooks, we recommend using a simple
+XML to Hash parser.
+
+If you are using Rails, we'd recommend [Hash.from_xml](https://apidock.com/rails/Hash/from_xml/class).
+
+```ruby
+notification = Hash.from_xml <<-XML
+  <?xml version="1.0" encoding="UTF-8"?>
+  <new_account_notification>
+    <account>
+      <account_code>1</account_code>
+      <username nil="true"></username>
+      <email>verena@example.com</email>
+      <first_name>Verena</first_name>
+      <last_name>Example</last_name>
+      <company_name nil="true"></company_name>
+    </account>
+  </new_account_notification>
+XML
+
+code = notification["new_account_notification"]["account"]["account_code"]
+puts "New Account with code #{code} created."
+```
+
+If you are not using Rails, we recommend you use [nokogiri](https://nokogiri.org/); however, heed security warnings
+about parse options. Although the XML should only be coming from Recurly, you should parse it as untrusted to be safe.
+Read more about the security implications of parsing untrusted XML in [this OWASP cheatsheet](https://cheatsheetseries.owasp.org/cheatsheets/XML_Security_Cheat_Sheet.html).

data/README.md

@@ -1,205 +1,23 @@
 # Recurly
 
-This gem is the ruby client for Recurly's V3 API (or "partner api"). It's currently Beta software
-and is not yet an official release. Documentation for the API can be [found here](https://partner-docs.recurly.com).
+This repository houses the official ruby client for Recurly's V3 API.
+
+> *Note*:
+> If you were looking for the V2 client, see the [master branch](https://github.com/recurly/recurly-client-ruby/tree/master).
 
 ## Getting Started
 
 ### Documentation
 
-Documentation can be found at this link: [https://www.rubydoc.info/github/recurly/recurly-client-ruby/3_0_0_beta](https://www.rubydoc.info/github/recurly/recurly-client-ruby/3_0_0_beta).
-This contains everything in the README as well as code-level documentation. We suggest starting there.
-
-### Installing
-
-This gem is a pre-release. In your Gemfile, add `recurly` as a dependency.
-
-```ruby
-gem 'recurly', '3.0.0.beta.5'
-```
-
-It's important that you lock on a specific version as there may be breaking changes between releases.
-All beta releases will have the format `3.0.0.beta.x` until we go live.
-
-### Creating a client
-
-Client instances are now explicitly created and referenced as opposed to V2's use of global, statically
-initialized clients.
-
-This makes multithreaded environments simpler and provides one location where every
-operation can be found (rather than having them spread out among classes).
-
-`Recurly::Client#new` initializes a new client. It requires an API key and a site id:
-
-```ruby
-API_KEY = '83749879bbde395b5fe0cc1a5abf8e5'
-SITE_ID = 'dqzlv9shi7wa'
-client = Recurly::Client.new(site_id: SITE_ID, api_key: API_KEY)
-# You may use the subdomain instead of the site_id if you do not know the site_id
-client = Recurly::Client.new(subdomain: 'mysite-prod', api_key: API_KEY)
-sub = client.get_subscription(subscription_id: 'abcd123456')
-```
-
-You can also pass the initializer a block. This will give you a client scoped for just that block:
-
-```ruby
-Recurly::Client.new(subdomain: 'mysite-prod', api_key: API_KEY) do |client|
-  sub = client.get_subscription(subscription_id: 'abcd123456')
-end
-```
-
-If you plan on using the client for more than one site, you should initialize a new client for each site.
-
-```ruby
-# Give a `site_id`
-client = Recurly::Client.new(api_key: API_KEY, site_id: SITE_ID)
-# Or use the subdomain
-client = Recurly::Client.new(api_key: API_KEY, subdomain: 'mysite-dev') 
-
-sub = client.get_subscription(subscription_id: 'abcd123456')
-
-# you should create a new client to connect to another site
-client = Recurly::Client.new(api_key: API_KEY, subdomain: 'mysite-prod') 
-sub = client.get_subscription(subscription_id: 'abcd7890')
-```
-
-### Operations
-
-The {Recurly::Client} contains every `operation` you can perform on the site as a list of methods. Each method is documented explaining
-the types and descriptions for each input and return type. You can view all available operations by looking at the `Instance Methods Summary` list
-on the {Recurly::Client} documentation page. Clicking a method will give you detailed information about its inputs and returns. Take the `create_account`
-operation as an example: {Recurly::Client#create_account}.
-
-### Pagination
-
-Pagination is done by the class `Recurly::Pager`. All `list_*` methods on the client return an instance of this class.
-The pager has an `each` method which accepts a block for each object in the entire list. Each page is fetched automatically
-for you presenting the elements as a single enumerable.
-
-```ruby
-plans = client.list_plans()
-plans.each do |plan|
-  puts "Plan: #{plan.id}"
-end
-```
-
-You may also paginate in chunks with `each_page`.
-
-```ruby
-plans = client.list_plans()
-plans.each_page do |data|
-  data.each do |plan|
-    puts "Plan: #{plan.id}"
-  end
-end
-```
-
-Both `Pager#each` and `Pager#each_page` return Enumerators if a block is not given. This allows you to use other Enumerator methods
-such as `map` or `each_with_index`.
-
-```ruby
-plans = client.list_plans()
-plans.each_page.each_with_index do |data, page_num|
-  puts "Page Number #{page_num}"
-  data.each do |plan|
-    puts "Plan: #{plan.id}"
-  end
-end
-```
-
-Pagination endpoints take a number of options to sort and filter the results. They can be passed in as keyword arguments.
-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
-}
-
-plans = client.list_plans(**options)
-plans.each do |plan|
-  puts "Plan: #{plan.id}"
-end
-```
-
-**A note on `limit`**:
-
-`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).
-
-
-### Creating Resources
-
-Currently, resources are created by passing in a `body` keyword argument in the form of a `Hash`.
-This Hash must follow the schema of the documented request type. For example, the `create_plan` operation
-takes a request of type {Recurly::Requests::PlanCreate}. Failing to conform to this schema will result in an argument
-error.
-
-```ruby
-require 'securerandom'
-
-code = SecureRandom.uuid
-plan_data = {
-  code: code,
-  interval_length: 1,
-  interval_unit: 'months',
-  name: code,
-  currencies: [
-    {
-      currency: 'USD',
-      setup_fee: 800,
-      unit_amount: 10
-    }
-  ]
-}
-
-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:
+> *Note*:
+> Until rubydoc.info respects our `.yardopts` file, see documentation [here](GETTING_STARTED.md).
 
-1. [API Errors](./lib/recurly/errors/api_errors.rb)
-2. [Network Errors](./lib/recurly/errors/network_errors.rb)
+Ruby documentation and the getting started instructions can be found
+on rubydoc.info: [https://www.rubydoc.info/github/recurly/recurly-client-ruby/](https://www.rubydoc.info/github/recurly/recurly-client-ruby/).
 
-You will normally be working with {Recurly::Errors::APIError}. You can catch specific or generic versions of these exceptions. Example:
+Documentation for the HTTP API and example code can be found
+[on our Developer Portal](https://developers.recurly.com/api/v2019-10-10/).
 
-```ruby
-begin
-  client = Recurly::Client.new(site_id: SITE_ID, api_key: API_KEY)
-  code = "iexistalready"
-  plan_data = {
-    code: code,
-    interval_length: 1,
-    interval_unit: 'months',
-    name: code,
-    currencies: [
-      {
-        currency: 'USD',
-        setup_fee: 800,
-        unit_amount: 10
-      }
-    ]
-  }
+### Contributing
 
-  plan = client.create_plan(body: plan_data)
-rescue Recurly::Errors::ValidationError => ex
-  puts ex.inspect
-  #=> #<Recurly::ValidationError: Recurly::ValidationError: Code 'iexistalready' already exists>
-  puts ex.recurly_error.inspect
-  #=> #<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::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
-```
+Please see our [Contributing Guide](CONTRIBUTING.md).