recurly 2.19.7 → 3.0.0.beta.1

data/lib/recurly/client.rb

@@ -0,0 +1,198 @@
+require 'faraday'
+require 'logger'
+require_relative './schema/json_parser'
+
+module Recurly
+  class Client
+    require_relative './client/operations'
+
+    BASE_URL = "https://partner-api.recurly.com/"
+
+    # The last result of the *X-RateLimit-Limit* header
+    # @return [Integer] The rate limit applied to this client.
+    attr_reader :rate_limit
+
+    # The last result of the *X-RateLimit-Remaining* header
+    # @return [Integer] The number of remaining requests, decrements per request.
+    attr_reader :rate_limit_remaining
+
+    # The last result of the *X-RateLimit-Reset* header
+    # @return [DateTime] The DateTime in which the request count will be reset.
+    attr_reader :rate_limit_reset
+
+    # Initialize a client. It requires an API key.
+    #
+    # @example
+    #   API_KEY = '83749879bbde395b5fe0cc1a5abf8e5'
+    #   SITE_ID = 'dqzlv9shi7wa'
+    #   client = Recurly::Client.new(site_id: SITE_ID, api_key: API_KEY)
+    #   # You can optionally use the subdomain instead of the site id
+    #   client = Recurly::Client.new(subdomain: 'mysite-prod', api_key: API_KEY)
+    #   sub = client.get_subscription(subscription_id: 'abcd123456')
+    # @example
+    #   # You can also pass the initializer a block. This will give you
+    #   # a client scoped for just that block
+    #   Recurly::Client.new(subdomain: 'mysite-prod', api_key: API_KEY) do |client|
+    #     sub = client.get_subscription(subscription_id: 'abcd123456')
+    #   end
+    # @example
+    #   # If you only plan on using the client for more than one site,
+    #   # you should initialize a new client for each site.
+    #
+    #   # 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')
+    #
+    # @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)
+      if site_id
+        @site_id = site_id
+      elsif subdomain
+        @site_id = "subdomain-#{subdomain}"
+      else
+        raise ArgumentError, "You must pass a site_id or subdomain argument to initialize the Client"
+      end
+
+      @log_level = options[:log_level] || Logger::WARN
+      @logger = Logger.new(STDOUT)
+      @logger.level = @log_level
+
+      @conn = Faraday.new(url: BASE_URL) do |faraday|
+        if @log_level == Logger::INFO
+          faraday.response :logger
+        end
+        faraday.basic_auth(api_key, '')
+        faraday.adapter :net_http do |http| # yields Net::HTTP
+          # Let's not use the bundled cert in production yet
+          # but we will use these certs for any other staging or dev environment
+          unless BASE_URL.end_with?('.recurly.com')
+            http.ca_file = File.join(File.dirname(__FILE__), '../data/ca-certificates.crt')
+          end
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.open_timeout = 50
+          http.read_timeout = 60
+          http.keep_alive_timeout = 60
+        end
+      end
+
+      # TODO this is undocumented until we finalize it
+      @extra_headers = options[:headers] || {}
+
+      # execute block with this client if given
+      yield(self) if block_given?
+    end
+
+    def next_page(pager)
+      run_request(:get, pager.next, nil, headers)
+    end
+
+    protected
+
+    def pager(path, **options)
+      Pager.new(client: self, path: path, options: options)
+    end
+
+    def get(path, **options)
+      response = run_request(:get, path, options.compact, headers)
+      raise_api_error!(response) if response.status != 200
+      JSONParser.parse(self, response.body)
+    rescue Faraday::ClientError => ex
+      raise_network_error!(ex)
+    end
+
+    def post(path, request_data, request_class, **options)
+      request = request_class.new(request_data)
+      request.validate!
+      logger.info("POST BODY #{JSON.dump(request_data)}")
+      response = run_request(:post, path, JSON.dump(request.attributes), headers)
+      raise_api_error!(response) if response.status != 201
+      JSONParser.parse(self, response.body)
+    rescue Faraday::ClientError => ex
+      raise_network_error!(ex)
+    end
+
+    def put(path, request_data, request_class, **options)
+      request = request_class.new(request_data)
+      request.validate!
+      logger.info("PUT BODY #{JSON.dump(request_data)}")
+      response = run_request(:put, path, JSON.dump(request_data), headers)
+      raise_api_error!(response) if ![200, 201].include?(response.status)
+      JSONParser.parse(self, response.body)
+    rescue Faraday::ClientError => ex
+      raise_network_error!(ex)
+    end
+
+    def delete(path, **options)
+      response = run_request(:delete, path, options.compact, headers)
+      raise_api_error!(response) if ![200, 201].include?(response.status)
+      JSONParser.parse(self, response.body)
+    rescue Faraday::ClientError => ex
+      raise_network_error!(ex)
+    end
+
+    protected
+
+    # Used by the operations.rb file to interpolate paths
+    attr_reader :site_id
+
+    private
+
+    # @return [Logger]
+    attr_reader :logger
+
+    def run_request(method, url, body, headers)
+      read_headers @conn.run_request(method, url, body, headers)
+    end
+
+    def raise_network_error!(ex)
+      error_class = case ex
+                    when Faraday::TimeoutError
+                      Errors::TimeoutError
+                    when Faraday::ConnectionFailed
+                      Errors::ConnectionFailed
+                    when Faraday::SSLError
+                      Errors::SSLError
+                    else
+                      Errors::NetworkError
+                    end
+
+      raise error_class, ex.message
+    end
+
+    def raise_api_error!(response)
+      error = JSONParser.parse(self, response.body)
+      error_class = Errors::APIError.error_class(error.type)
+      raise error_class.new(response, error)
+    end
+
+    def read_headers(response)
+      @rate_limit = response.headers['x-ratelimit-limit'].to_i
+      @rate_limit_remaining = response.headers['x-ratelimit-remaining'].to_i
+      @rate_limit_reset = Time.at(response.headers['x-ratelimit-reset'].to_i).to_datetime
+      response
+    end
+
+    def headers
+      {
+        'Accept' => "application/vnd.recurly.#{api_version}", # got this method from operations.rb
+        'Content-Type' => 'application/json',
+        'User-Agent' => "Recurly/#{VERSION}; #{RUBY_DESCRIPTION}"
+      }.merge(@extra_headers)
+    end
+
+    def interpolate_path(path, **options)
+      path = path.gsub("{", "%{")
+      path % options
+    end
+  end
+end

data/lib/recurly/errors/api_errors.rb

@@ -0,0 +1,35 @@
+module Recurly
+  module Errors
+    class BadRequestError < Errors::APIError; end
+
+    class InternalServerError < Errors::APIError; end
+
+    class ImmutableSubscriptionError < Errors::APIError; end
+
+    class InvalidApiKeyError < Errors::APIError; end
+
+    class InvalidApiVersionError < Errors::APIError; end
+
+    class InvalidContentTypeError < Errors::APIError; end
+
+    class InvalidPermissionsError < Errors::APIError; end
+
+    class InvalidTokenError < Errors::APIError; end
+
+    class NotFoundError < Errors::APIError; end
+
+    class SimultaneousRequestError < Errors::APIError; end
+
+    class TransactionError < Errors::APIError; end
+
+    class UnauthorizedError < Errors::APIError; end
+
+    class UnavailableInApiVersionError < Errors::APIError; end
+
+    class UnknownApiVersionError < Errors::APIError; end
+
+    class ValidationError < Errors::APIError; end
+
+    class MissingFeatureError < Errors::APIError; end
+  end
+end

data/lib/recurly/errors/network_errors.rb

@@ -0,0 +1,8 @@
+module Recurly
+  module Errors
+    class NetworkError < StandardError; end
+    class TimeoutError < NetworkError; end
+    class ConnectionFailed < NetworkError; end
+    class SSLError < NetworkError; end
+  end
+end

data/lib/recurly/errors.rb

@@ -0,0 +1,34 @@
+module Recurly
+  module Errors
+    class APIError < StandardError
+      # @!attribute recurly_error
+      #   @return [Recurly::Resources::Error] The {Recurly::Resources::Error} object
+      attr_reader :recurly_error
+
+      # Looks up an Error class by name
+      # @example
+      #   Errors.error_class('BadRequestError')
+      #   #=> Errors::BadRequestError
+      # @param error_key [String]
+      # @return [Errors::APIError,Errors::NetworkError]
+      def self.error_class(error_key)
+        class_name = error_key.split('_').map(&:capitalize).join
+        class_name += "Error" unless class_name.end_with?("Error")
+        Errors.const_get(class_name)
+      end
+
+      def initialize(response, error)
+        super("#{self.class.name}: #{error.message}")
+        @response = response
+        @recurly_error = error
+      end
+
+      def status_code
+        @response.status
+      end
+    end
+  end
+
+  require_relative "./errors/api_errors"
+  require_relative "./errors/network_errors"
+end

data/lib/recurly/pager.rb

@@ -0,0 +1,119 @@
+module Recurly
+  class Pager
+    attr_accessor :client
+    attr_reader :data, :next
+
+    def initialize(client:, path:, options: {})
+      @client = client
+      @path = path
+      @options = options
+      @next = build_path(@path, @options)
+    end
+
+    # Enumerates each "page" from the server.
+    # This method yields a given block with the array of items
+    # in the page `data` and the page number the pagination is on
+    # `page_num` which is 0-indexed.
+    #
+    # @example
+    #   plans = client.list_plans()
+    #   plans.each_page do |data|
+    #     data.each do |plan|
+    #       puts "Plan: #{plan.id}"
+    #     end
+    #   end
+    # @example
+    #   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
+    def each_page(&block)
+      if block_given?
+        page_enumerator.each(&block)
+      else
+        page_enumerator
+      end
+    end
+
+    # Enumerates each item on the server. Each item is yielded to the
+    # block presenting the effect of a continuous stream of items.
+    # In reality, the pager is fetching blocks of data (pages) under the hood.
+    # This method yields a given block with the next item to process.
+    #
+    # @example
+    #   plans = client.list_plans()
+    #   plans.each do |plan|
+    #     puts "Plan: #{plan.id}"
+    #   end
+    # @example
+    #   plans = client.list_plans()
+    #   plans.each.each_with_index do |plan, idx|
+    #     puts "Plan #{idx}: #{plan.id}"
+    #   end
+    def each(&block)
+      if block_given?
+        item_enumerator.each(&block)
+      else
+        item_enumerator
+      end
+    end
+
+    def has_more?
+      !!@has_more
+    end
+
+    def requires_client?
+      true
+    end
+
+    private
+
+    def from_json(data)
+      @data = data['data'].map do |resource_data|
+        JSONParser.from_json(resource_data)
+      end
+      @next = data['next']
+      @has_more = data['has_more']
+    end
+
+    def item_enumerator
+      Enumerator.new do |yielder|
+        page_enumerator.each do |data|
+          data.each do |item|
+            yielder << item
+          end
+        end
+      end
+    end
+
+    def page_enumerator
+      Enumerator.new do |yielder|
+        loop do
+          fetch_next!
+          yielder << data
+          unless has_more?
+            rewind!
+            break
+          end
+        end
+      end
+    end
+
+    def fetch_next!
+      response = @client.next_page(self)
+      from_json(JSON.parse(response.body))
+    end
+
+    def rewind!
+      @data = []
+      @next = build_path(@path, @options)
+    end
+
+    def build_path(path, options)
+      "#{path}?#{URI.encode_www_form(options)}"
+    end
+  end
+end

data/lib/recurly/request.rb

@@ -0,0 +1,30 @@
+module Recurly
+  # This class represents a request to Recurly.
+  # It's used to validate requests data as well as
+  # cast and serialize the request data to JSON.
+  class Request
+    extend Schema::SchemaFactory
+    extend Schema::RequestCaster
+    include Schema::SchemaValidator
+
+    attr_reader :attributes
+
+    def ==(other_resource)
+      self.attributes == other_resource.attributes
+    end
+
+    protected
+
+    def initialize(attributes = {})
+      @attributes = self.class.cast(attributes.clone)
+    end
+
+    def to_s
+      self.inspect
+    end
+
+    def schema
+      self.class.schema
+    end
+  end
+end

data/lib/recurly/requests/account_acquisition_updatable.rb

@@ -0,0 +1,22 @@
+module Recurly
+  module Requests
+    class AccountAcquisitionUpdatable < Request
+
+      # @!attribute campaign
+      #   @return [String] An arbitrary identifier for the marketing campaign that led to the acquisition of this account.
+      define_attribute :campaign, String
+
+      # @!attribute channel
+      #   @return [String] The channel through which the account was acquired.
+      define_attribute :channel, String, {:enum => ["referral", "social_media", "email", "paid_search", "organic_search", "direct_traffic", "marketing_content", "blog", "events", "outbound_sales", "advertising", "public_relations", "other"]}
+
+      # @!attribute cost
+      #   @return [Hash] Account balance
+      define_attribute :cost, Hash
+
+      # @!attribute subchannel
+      #   @return [String] An arbitrary subchannel string representing a distinction/subcategory within a broader channel.
+      define_attribute :subchannel, String
+    end
+  end
+end

data/lib/recurly/requests/account_create_only.rb

@@ -0,0 +1,18 @@
+module Recurly
+  module Requests
+    class AccountCreateOnly < Request
+
+      # @!attribute acquisition
+      #   @return [AccountAcquisitionUpdatable]
+      define_attribute :acquisition, :AccountAcquisitionUpdatable
+
+      # @!attribute code
+      #   @return [String] The unique identifier of the account. This cannot be changed once the account is created.
+      define_attribute :code, String
+
+      # @!attribute shipping_addresses
+      #   @return [Array[ShippingAddressCreate]]
+      define_attribute :shipping_addresses, Array, {:item_type => :ShippingAddressCreate}
+    end
+  end
+end

data/lib/recurly/requests/account_updatable.rb

@@ -0,0 +1,50 @@
+module Recurly
+  module Requests
+    class AccountUpdatable < Request
+
+      # @!attribute address
+      #   @return [Address]
+      define_attribute :address, :Address
+
+      # @!attribute billing_info
+      #   @return [BillingInfoCreate]
+      define_attribute :billing_info, :BillingInfoCreate
+
+      # @!attribute cc_emails
+      #   @return [String] Additional email address that should receive account correspondence. These should be separated only by commas. These CC emails will receive all emails that the `email` field also receives.
+      define_attribute :cc_emails, String
+
+      # @!attribute company
+      #   @return [String]
+      define_attribute :company, String
+
+      # @!attribute email
+      #   @return [String] The email address used for communicating with this customer. The customer will also use this email address to log into your hosted account management pages. This value does not need to be unique.
+      define_attribute :email, String
+
+      # @!attribute first_name
+      #   @return [String]
+      define_attribute :first_name, String
+
+      # @!attribute last_name
+      #   @return [String]
+      define_attribute :last_name, String
+
+      # @!attribute preferred_locale
+      #   @return [String] Used to determine the language and locale of emails sent on behalf of the merchant to the customer. The list of locales is restricted to those the merchant has enabled on the site.
+      define_attribute :preferred_locale, String, {:enum => ["da-DK", "de-CH", "de-DE", "en-AU", "en-CA", "en-GB", "en-NZ", "en-US", "es-ES", "es-MX", "es-US", "fr-CA", "fr-FR", "hi-IN", "ja-JP", "nl-BE", "nl-NL", "pt-BR", "pt-PT", "ru-RU", "tr-TR", "zh-CN"]}
+
+      # @!attribute tax_exempt
+      #   @return [Boolean] The tax status of the account. `true` exempts tax on the account, `false` applies tax on the account.
+      define_attribute :tax_exempt, :Boolean
+
+      # @!attribute username
+      #   @return [String] A secondary value for the account.
+      define_attribute :username, String
+
+      # @!attribute vat_number
+      #   @return [String] The VAT number of the account (to avoid having the VAT applied). This is only used for manually collected invoices.
+      define_attribute :vat_number, String
+    end
+  end
+end

data/lib/recurly/requests/add_on_create.rb

@@ -0,0 +1,38 @@
+module Recurly
+  module Requests
+    class AddOnCreate < Request
+
+      # @!attribute accounting_code
+      #   @return [String] Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on's code.
+      define_attribute :accounting_code, String
+
+      # @!attribute code
+      #   @return [String] The unique identifier for the add-on within its plan.
+      define_attribute :code, String
+
+      # @!attribute currencies
+      #   @return [Array[String]] Add-on pricing
+      define_attribute :currencies, Array, {:item_type => String}
+
+      # @!attribute default_quantity
+      #   @return [Integer] Default quantity for the hosted pages.
+      define_attribute :default_quantity, Integer
+
+      # @!attribute display_quantity
+      #   @return [Boolean] Determines if the quantity field is displayed on the hosted pages for the add-on.
+      define_attribute :display_quantity, :Boolean
+
+      # @!attribute name
+      #   @return [String] Describes your add-on and will appear in subscribers' invoices.
+      define_attribute :name, String
+
+      # @!attribute [r] plan_id
+      #   @return [String] Plan ID
+      define_attribute :plan_id, String, {:read_only => true}
+
+      # @!attribute tax_code
+      #   @return [String] Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.
+      define_attribute :tax_code, String
+    end
+  end
+end

data/lib/recurly/requests/add_on_update.rb

@@ -0,0 +1,38 @@
+module Recurly
+  module Requests
+    class AddOnUpdate < Request
+
+      # @!attribute accounting_code
+      #   @return [String] Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on's code.
+      define_attribute :accounting_code, String
+
+      # @!attribute code
+      #   @return [String] The unique identifier for the add-on within its plan.
+      define_attribute :code, String
+
+      # @!attribute currencies
+      #   @return [Array[String]] Add-on pricing
+      define_attribute :currencies, Array, {:item_type => String}
+
+      # @!attribute default_quantity
+      #   @return [Integer] Default quantity for the hosted pages.
+      define_attribute :default_quantity, Integer
+
+      # @!attribute display_quantity
+      #   @return [Boolean] Determines if the quantity field is displayed on the hosted pages for the add-on.
+      define_attribute :display_quantity, :Boolean
+
+      # @!attribute [r] id
+      #   @return [String] Add-on ID
+      define_attribute :id, String, {:read_only => true}
+
+      # @!attribute name
+      #   @return [String] Describes your add-on and will appear in subscribers' invoices.
+      define_attribute :name, String
+
+      # @!attribute tax_code
+      #   @return [String] Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.
+      define_attribute :tax_code, String
+    end
+  end
+end

data/lib/recurly/requests/address.rb

@@ -0,0 +1,42 @@
+module Recurly
+  module Requests
+    class Address < Request
+
+      # @!attribute city
+      #   @return [String] City
+      define_attribute :city, String
+
+      # @!attribute country
+      #   @return [String] Country, 2-letter ISO code.
+      define_attribute :country, String
+
+      # @!attribute first_name
+      #   @return [String] First name
+      define_attribute :first_name, String
+
+      # @!attribute last_name
+      #   @return [String] Last name
+      define_attribute :last_name, String
+
+      # @!attribute phone
+      #   @return [String] Phone number
+      define_attribute :phone, String
+
+      # @!attribute postal_code
+      #   @return [String] Zip or postal code.
+      define_attribute :postal_code, String
+
+      # @!attribute region
+      #   @return [String] State or province.
+      define_attribute :region, String
+
+      # @!attribute street1
+      #   @return [String] Street 1
+      define_attribute :street1, String
+
+      # @!attribute street2
+      #   @return [String] Street 2
+      define_attribute :street2, String
+    end
+  end
+end