recurly 2.18.22 → 3.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89370fbc69e2a1dc5dc317f45c0b3be37fad9b22d7fd0186416312f6cdfbe68c
-  data.tar.gz: 34a070a7121166d2e810bbf27313d792e657f681c74ce9139938e52cc4924f85
+  metadata.gz: 4560816624b25f0c01b6403a22f7b6425c9b7dde31ef860544d4eb3b7bc36fc5
+  data.tar.gz: 154f6697035218babd3b843c820e17fd7650cc275ce1f931eb0800204b67b9ea
 SHA512:
-  metadata.gz: a56882820ac3dd3cc339e5d9e0d23ab3d17c425754199f6ed7e39b8cddb75ab5c4760a5ccc4b948552f85005ce8ea1256b5e4dd29bd57747bc7e5b2476081e71
-  data.tar.gz: 89dde5248e08a6f9b2d521df965c5de159fd73d5e96518a8d4e78e878de50b44f464aebbef0aaf3aa493622bb1919de18f7ab48b98bae29615267a0575688152
+  metadata.gz: e1c15b8a70794c06a3d064c4d4b830975d6f5c4aeddfa14a7d5387294d2ecb1ea42f8e96070cf6adb4742a606ed36b2e8fd3e97c96b39688da2099ab72a5159d
+  data.tar.gz: bc16dd1d21814913aa3cb3e23d85bf745a14f47a4fe22ec1931171eef20adae9333f1ad990deacc27857f53a6941b361452123e97a32c697a05c19530e2d920b

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+*.gem
+coverage

data/.rspec

@@ -0,0 +1,2 @@
+--format progress
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.0
+before_install: gem install bundler -v 1.14.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in recurly.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Recurly Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,150 +1,198 @@
-# Recurly [![Build Status](https://secure.travis-ci.org/recurly/recurly-client-ruby.png?branch=master)](http://travis-ci.org/recurly/recurly-client-ruby) [![Gem Version](https://badge.fury.io/rb/recurly.svg)](http://badge.fury.io/rb/recurly)
+# Recurly
 
-<https://github.com/recurly/recurly-client-ruby>
+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).
 
-[Recurly](https://recurly.com/)'s Ruby client library is an interface to its
-[REST API](https://dev.recurly.com/docs/getting-started).
+## Getting Started
 
-You can also look at [rubydocs](http://www.rubydoc.info/github/recurly/recurly-client-ruby/master)
-to see documentation on the classes and methods available.
+### Documentation
 
-## Installation
+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.
 
-Recurly is packaged as a Ruby gem. We recommend you install it with
-[Bundler](http://gembundler.com/) by adding the following line to your Gemfile:
+### Installing
 
-``` ruby
-gem 'recurly', '~> 2.18.22'
-```
-
-Recurly will automatically use [Nokogiri](http://nokogiri.org/) (for a nice
-speed boost) if it's available and loaded in your app's environment.
-
-## Configuration
+This gem is a pre-release. In your Gemfile, add `recurly` as a dependency.
 
-Use the following template to configure Recurly:
-
-``` ruby
-Recurly.subdomain      = ENV['RECURLY_SUBDOMAIN']
-Recurly.api_key        = ENV['RECURLY_API_KEY']
+```ruby
+gem 'recurly', '3.0.0.beta.1'
 ```
 
-> Note: In Rails, these would be added in an initializer `config/initializers/recurly.rb`.
-
-Configure the client library with
-[your API credentials](https://app.recurly.com/go/developer/api_access).
+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.
 
-* `RECURLY_SUBDOMAIN` should contain subdomain for your recurly account.
-* `RECURLY_API_KEY` is your "Private API Key" which can be found under "API Credentials" on the `api_access` admin page.
+### Creating a client
 
-The default currency is USD. To override with a different code:
+Client instances are now explicitly created and referenced as opposed to V2's use of global, statically
+initialized clients.
 
-``` ruby
-Recurly.default_currency = 'EUR' # Assign nil to disable the default entirely.
-```
+This makes multithreaded environments simpler and provides one location where every
+operation can be found (rather than having them spread out among classes).
 
-If you are using [Recurly.js](https://js.recurly.com) you can store "Public API Key" (which can be found
-under "API Credentials" on the `api_access` admin page):
+`Recurly::Client#new` initializes a new client. It requires an API key and a site id:
 
-``` ruby
-Recurly.js.public_key = ENV['RECURLY_PUBLIC_API_KEY']
+```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')
 ```
 
-Then, in your Rails project you can create `recurly_service.js.erb` file and
-[configure](https://docs.recurly.com/js/#configure) recurly.js with public key this way:
+You can also pass the initializer a block. This will give you a client scoped for just that block:
 
-``` js
-recurly.configure({ publicKey: '<%= Recurly.js.public_key %>'});
+```ruby
+Recurly::Client.new(subdomain: 'mysite-prod', api_key: API_KEY) do |client|
+  sub = client.get_subscription(subscription_id: 'abcd123456')
+end
 ```
 
-The client library currently uses a Net::HTTP adapter. If you need to
-configure the settings passed to Net::HTTP (e.g., an SSL certificates path or timeout lengths),
-make sure you assign them when initializing the library:
+If you only plan on using the client for more than one site, you should initialize a new client for each site.
 
-``` ruby
-Recurly::API.net_http = {
-  ca_path: "/etc/ssl/certs",
-  open_timeout: 5, # 5 seconds (defaults to 60)
-  read_timeout: 45 # 45 seconds (defaults to 60)
-}
-```
-
-To see which keys are supported for this Hash, see the `Attributes` section
-of the [Net::HTTP documentation](http://ruby-doc.org/stdlib-2.4.1/libdoc/net/http/rdoc/Net/HTTP.html) for your ruby version.
+```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') 
 
-## Multi-Threaded Configuration
-If you are using the client in a multi-threaded environment and require a different configuration per
-thread you can use the following within the thread's context:
+sub = client.get_subscription(subscription_id: 'abcd123456')
 
-``` ruby
-Recurly.config({
-  subdomain: ENV['RECURLY_SUBDOMAIN']
-  api_key: ENV['RECURLY_API_KEY'],
-  default_currency: "US"
-})
+# 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')
 ```
 
-Any configuration items you do not include in the above config call will be defaulted to the standard
-configuration items. For example if you do not define default_currency then Recurly.default_currency
-will be used.
-
-## Supported Ruby Versions
-
-Recurly will support whichever versions the [Ruby maintainers are supporting](https://www.ruby-lang.org/en/downloads/branches/).
-We support all versions with status `* maintenance`. We do not support `eol` versions or `preview` versions. This library
-may work on EOL versions of ruby, but we may not be able to support you if you use one.
-
-## Nokogiri Support
+### Operations
 
-For now, we are still running the tests on 2.0 and below but without `nokogiri` and only `rexml`. Nokogiri is
-no longer supported on 1.9 or 2.0 and has patched known vulnerabilities since dropping support.
-If you must run one of these rubies (this includes jruby1.7), you must use rexml and not nokogiri.
+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}.
 
-## Usage
+### Pagination
 
-Instructions and examples are available on
-[Recurly's documentation site](https://dev.recurly.com/docs/getting-started).
+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.
 
-Recurly's gem API is available
-[here](http://rubydoc.info/gems/recurly/frames/Recurly).
-
-## Support
-
-- [https://support.recurly.com](https://support.recurly.com)
-- [stackoverflow](http://stackoverflow.com/questions/tagged/recurly)
-
-## Contributing
-
-Developing for the Recurly gem is easy with [Bundler](http://gembundler.com/).
-
-Fork and clone the repository, `cd` into the directory, and, with a Ruby of your choice
-(1.9.3 or greater), set up your environment.
+```ruby
+plans = client.list_plans()
+plans.each do |plan|
+  puts "Plan: #{plan.id}"
+end
+```
 
-If you don't have Bundler installed, install it with the following command:
+You may also paginate in chunks with `each_page`.
 
-``` bash
-$ [sudo] gem install bundler
+```ruby
+plans = client.list_plans()
+plans.each_page do |data|
+  data.each do |plan|
+    puts "Plan: #{plan.id}"
+  end
+end
 ```
 
-And bundle:
-
-``` bash
-$ bundle --path=vendor/bundle
+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
 ```
 
-You should now be able to run the test suite with Rake:
+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 = {
+  state: :active, # only active plans
+  sort: :updated_at,
+  order: :asc,
+  begin_time: DateTime.new(2017,1,1), # January 1st 2017,
+  end_time: DateTime.now
+}
 
-``` bash
-$ bundle exec rake
+plans = client.list_plans(**options)
+plans.each do |plan|
+  puts "Plan: #{plan.id}"
+end
 ```
 
-To run the suite using Nokogiri:
+### 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
+    }
+  ]
+}
 
-``` bash
-$ XML=nokogiri bundle exec rake
+plan = client.create_plan(body: plan_data)
 ```
 
-If you plan on submitting a patch, please write tests for it (we use
-[MiniTest::Spec](http://bfts.rubyforge.org/minitest/MiniTest/Expectations.html)).
-
-If everything looks good, submit a pull request on GitHub and we'll bring in your changes.
+### 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(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
+      }
+    ]
+  }
+
+  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
+```

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/bundle

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'bundle' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "rubygems"
+
+m = Module.new do
+    module_function
+
+  def invoked_as_script?
+    File.expand_path($0) == File.expand_path(__FILE__)
+  end
+
+  def env_var_version
+    ENV["BUNDLER_VERSION"]
+  end
+
+  def cli_arg_version
+    return unless invoked_as_script? # don't want to hijack other binstubs
+    return unless "update".start_with?(ARGV.first || " ") # must be running `bundle update`
+    bundler_version = nil
+    update_index = nil
+    ARGV.each_with_index do |a, i|
+      if update_index && update_index.succ == i && a =~ Gem::Version::ANCHORED_VERSION_PATTERN
+        bundler_version = a
+      end
+      next unless a =~ /\A--bundler(?:[= ](#{Gem::Version::VERSION_PATTERN}))?\z/
+      bundler_version = $1 || ">= 0.a"
+      update_index = i
+    end
+    bundler_version
+  end
+
+  def gemfile
+    gemfile = ENV["BUNDLE_GEMFILE"]
+    return gemfile if gemfile && !gemfile.empty?
+
+    File.expand_path("../../Gemfile", __FILE__)
+  end
+
+  def lockfile
+    lockfile =
+      case File.basename(gemfile)
+      when "gems.rb" then gemfile.sub(/\.rb$/, gemfile)
+      else "#{gemfile}.lock"
+      end
+    File.expand_path(lockfile)
+  end
+
+  def lockfile_version
+    return unless File.file?(lockfile)
+    lockfile_contents = File.read(lockfile)
+    return unless lockfile_contents =~ /\n\nBUNDLED WITH\n\s{2,}(#{Gem::Version::VERSION_PATTERN})\n/
+    Regexp.last_match(1)
+  end
+
+  def bundler_version
+    @bundler_version ||= begin
+      env_var_version || cli_arg_version ||
+        lockfile_version || "#{Gem::Requirement.default}.a"
+    end
+  end
+
+  def load_bundler!
+    ENV["BUNDLE_GEMFILE"] ||= gemfile
+
+    # must dup string for RG < 1.8 compatibility
+    activate_bundler(bundler_version.dup)
+  end
+
+  def activate_bundler(bundler_version)
+    if Gem::Version.correct?(bundler_version) && Gem::Version.new(bundler_version).release < Gem::Version.new("2.0")
+      bundler_version = "< 2"
+    end
+    gem_error = activation_error_handling do
+      gem "bundler", bundler_version
+    end
+    return if gem_error.nil?
+    require_error = activation_error_handling do
+      require "bundler/version"
+    end
+    return if require_error.nil? && Gem::Requirement.new(bundler_version).satisfied_by?(Gem::Version.new(Bundler::VERSION))
+    warn "Activating bundler (#{bundler_version}) failed:\n#{gem_error.message}\n\nTo install the version of bundler this project requires, run `gem install bundler -v '#{bundler_version}'`"
+    exit 42
+  end
+
+  def activation_error_handling
+    yield
+    nil
+  rescue StandardError, LoadError => e
+    e
+  end
+end
+
+m.load_bundler!
+
+if m.invoked_as_script?
+  load Gem.bin_path("bundler", "bundle")
+end

data/bin/coderay

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'coderay' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("coderay", "coderay")

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "recurly"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/htmldiff

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'htmldiff' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("diff-lcs", "htmldiff")

data/bin/ldiff

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'ldiff' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("diff-lcs", "ldiff")

data/bin/pry

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'pry' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("pry", "pry")

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")