Initial Commit

.gitignore

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

.rspec

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

.travis.yml

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

Gemfile

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

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.

README.md

@@ -0,0 +1,178 @@
+# Recurly
+
+This gem is the ruby client to the v3, aka API next, aka PAPI, version of Recurly's API. Parts of this gem are generated
+by the `recurly-client-gen` project.
+
+## Getting Started
+
+Read this before starting to get an overview of how to use this library.
+
+### Creating a client
+
+Client instances are now explicitly created and managed as opposed to the previous approach of opaque, statically
+initialized clients. This makes multithreaded environments a lot easier and also provides one place where every
+operation on recurly can be found (rather than having them spread out amongst classes).
+
+`Recurly::Client#new` initializes a new client. It requires an API key:
+
+```ruby
+API_KEY = '83749879bbde395b5fe0cc1a5abf8e5'
+SITE_ID = 'dqzlv9shi7wa'
+client = Recurly::Client.new(api_key: API_KEY)
+sub = client.get_subscription(site_id: SITE_ID, 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(site_id: SITE_ID, subscription_id: 'abcd123456')
+end
+```
+
+If you only plan on using the client for one site, you may pass in a `site_id` or a `subdomain` to the initializer.
+This makes all `site_id` parameters optional.
+
+```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') 
+
+# You no longer need to provide `site_id` to these methods
+sub = client.get_subscription(subscription_id: 'abcd123456')
+```
+
+### 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 = {
+  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
+```
+
+### 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(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
+```

Rakefile

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

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

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")

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__)