recurly 2.18.21 → 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