recurly 3.3.0 → 3.6.0

data/lib/recurly.rb

@@ -7,6 +7,7 @@ require "recurly/requests"
 require "recurly/resources"
 require "recurly/http"
 require "recurly/errors"
+require "recurly/connection_pool"
 require "recurly/client"
 
 module Recurly

data/lib/recurly/client.rb

@@ -1,18 +1,25 @@
-require "faraday"
 require "logger"
 require "erb"
+require "net/https"
+require "base64"
+require "securerandom"
 require_relative "./schema/json_parser"
 require_relative "./schema/file_parser"
-require_relative "./client/adapter"
 
 module Recurly
   class Client
     require_relative "./client/operations"
 
-    BASE_URL = "https://v3.recurly.com/"
+    BASE_HOST = "v3.recurly.com"
+    BASE_PORT = 443
+    CA_FILE = File.join(File.dirname(__FILE__), "../data/ca-certificates.crt")
     BINARY_TYPES = [
       "application/pdf",
-    ]
+    ].freeze
+    JSON_CONTENT_TYPE = "application/json"
+    MAX_RETRIES = 3
+    LOG_LEVELS = %i(debug info warn error fatal).freeze
+    BASE36_ALPHABET = (("0".."9").to_a + ("a".."z").to_a).freeze
 
     # Initialize a client. It requires an API key.
     #
@@ -38,27 +45,42 @@ module Recurly
     #   sub = client.get_subscription(subscription_id: 'uuid-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)
+    # @param logger [Logger] A logger to use. Defaults to creating a new STDOUT logger with level WARN.
+    def initialize(api_key:, site_id: nil, subdomain: nil, logger: nil)
       set_site_id(site_id, subdomain)
-      set_options(options)
-      set_faraday_connection(api_key)
+      set_api_key(api_key)
+
+      if logger.nil?
+        @logger = Logger.new(STDOUT).tap do |l|
+          l.level = Logger::WARN
+        end
+      else
+        unless LOG_LEVELS.all? { |lev| logger.respond_to?(lev) }
+          raise ArgumentError, "You must pass in a logger implementation that responds to the following messages: #{LOG_LEVELS}"
+        end
+        @logger = logger
+      end
+
+      if @logger.level < Logger::INFO
+        msg = <<-MSG
+        The Recurly logger should not be initialized
+        beyond the level INFO. It is currently configured to emit
+        headers and request / response bodies. This has the potential to leak
+        PII and other sensitive information and should never be used in production.
+        MSG
+        log_warn("SECURITY_WARNING", message: msg)
+      end
 
       # execute block with this client if given
       yield(self) if block_given?
     end
 
-    def next_page(pager)
-      req = HTTP::Request.new(:get, pager.next, nil)
-      faraday_resp = run_request(req, headers)
-      handle_response! req, faraday_resp
-    end
-
     protected
 
+    # Used by the operations.rb file to interpolate paths
+    attr_reader :site_id
+
     def pager(path, **options)
-      path = scope_by_site(path, **options)
       Pager.new(
         client: self,
         path: path,
@@ -66,70 +88,158 @@ module Recurly
       )
     end
 
+    def head(path, **options)
+      request = Net::HTTP::Head.new build_url(path, options)
+      set_headers(request, options[:headers])
+      http_response = run_request(request, options)
+      handle_response! request, http_response
+    end
+
     def get(path, **options)
-      path = scope_by_site(path, **options)
-      request = HTTP::Request.new(:get, path, nil)
-      faraday_resp = run_request(request, headers)
-      handle_response! request, faraday_resp
-    rescue Faraday::ClientError => ex
-      raise_network_error!(ex)
+      request = Net::HTTP::Get.new build_url(path, options)
+      set_headers(request, options[:headers])
+      http_response = run_request(request, options)
+      handle_response! request, http_response
     end
 
     def post(path, request_data, request_class, **options)
       request_class.new(request_data).validate!
-      path = scope_by_site(path, **options)
-      request = HTTP::Request.new(:post, path, JSON.dump(request_data))
-      faraday_resp = run_request(request, headers)
-      handle_response! request, faraday_resp
-    rescue Faraday::ClientError => ex
-      raise_network_error!(ex)
+      request = Net::HTTP::Post.new build_url(path, options)
+      request.set_content_type(JSON_CONTENT_TYPE)
+      set_headers(request, options[:headers])
+      request.body = JSON.dump(request_data)
+      http_response = run_request(request, options)
+      handle_response! request, http_response
     end
 
     def put(path, request_data = nil, request_class = nil, **options)
-      path = scope_by_site(path, **options)
-      request = HTTP::Request.new(:put, path)
+      request = Net::HTTP::Put.new build_url(path, options)
+      request.set_content_type(JSON_CONTENT_TYPE)
+      set_headers(request, options[:headers])
       if request_data
         request_class.new(request_data).validate!
-        logger.info("PUT BODY #{JSON.dump(request_data)}")
-        request.body = JSON.dump(request_data)
+        json_body = JSON.dump(request_data)
+        request.body = json_body
       end
-      faraday_resp = run_request(request, headers)
-      handle_response! request, faraday_resp
-    rescue Faraday::ClientError => ex
-      raise_network_error!(ex)
+      http_response = run_request(request, options)
+      handle_response! request, http_response
     end
 
     def delete(path, **options)
-      path = scope_by_site(path, **options)
-      request = HTTP::Request.new(:delete, path, nil)
-      faraday_resp = run_request(request, headers)
-      handle_response! request, faraday_resp
-    rescue Faraday::ClientError => ex
-      raise_network_error!(ex)
+      request = Net::HTTP::Delete.new build_url(path, options)
+      set_headers(request, options[:headers])
+      http_response = run_request(request, options)
+      handle_response! request, http_response
     end
 
-    protected
+    private
 
-    # Used by the operations.rb file to interpolate paths
-    attr_reader :site_id
+    @connection_pool = Recurly::ConnectionPool.new
 
-    private
+    class << self
+      # @return [Recurly::ConnectionPool]
+      attr_accessor :connection_pool
+    end
+
+    def run_request(request, options = {})
+      self.class.connection_pool.with_connection do |http|
+        set_http_options(http, options)
+
+        retries = 0
+
+        begin
+          http.start unless http.started?
+          log_attrs = {
+            method: request.method,
+            path: request.path,
+          }
+          if @logger.level < Logger::INFO
+            log_attrs[:request_body] = request.body
+            # No need to log the authorization header
+            headers = request.to_hash.reject { |k, _| k&.downcase == "authorization" }
+            log_attrs[:request_headers] = headers
+          end
+
+          log_info("Request", **log_attrs)
+          start = Time.now
+          response = http.request(request)
+          elapsed = Time.now - start
+
+          # GETs are safe to retry after a server error, requests with an Idempotency-Key will return the prior response
+          if response.kind_of?(Net::HTTPServerError) && request.is_a?(Net::HTTP::Get)
+            retries += 1
+            log_info("Retrying", retries: retries, **log_attrs)
+            start = Time.now
+            response = http.request(request) if retries < MAX_RETRIES
+            elapsed = Time.now - start
+          end
+
+          if @logger.level < Logger::INFO
+            log_attrs[:response_body] = response.body
+            log_attrs[:response_headers] = response.to_hash
+          end
+          log_info("Response", time_ms: (elapsed * 1_000).floor, status: response.code, **log_attrs)
+
+          response
+        rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ECONNABORTED,
+               Errno::EPIPE, Errno::ETIMEDOUT, Net::OpenTimeout, EOFError, SocketError => ex
+          retries += 1
+          if retries < MAX_RETRIES
+            retry
+          end
+
+          if ex.kind_of?(Net::OpenTimeout) || ex.kind_of?(Errno::ETIMEDOUT)
+            raise Recurly::Errors::TimeoutError, "Request timed out"
+          end
+
+          raise Recurly::Errors::ConnectionFailedError, "Failed to connect to Recurly: #{ex.message}"
+        rescue Net::ReadTimeout, Timeout::Error
+          raise Recurly::Errors::TimeoutError, "Request timed out"
+        rescue OpenSSL::SSL::SSLError => ex
+          raise Recurly::Errors::SSLError, ex.message
+        rescue StandardError => ex
+          raise Recurly::Errors::NetworkError, ex.message
+        end
+      end
+    end
 
-    # @return [Logger]
-    attr_reader :logger
+    def set_headers(request, additional_headers = {})
+      request["Accept"] = "application/vnd.recurly.#{api_version}".chomp # got this method from operations.rb
+      request["Authorization"] = "Basic #{Base64.encode64(@api_key)}".chomp
+      request["User-Agent"] = "Recurly/#{VERSION}; #{RUBY_DESCRIPTION}"
 
-    def run_request(request, headers)
-      read_headers @conn.run_request(request.method, request.path, request.body, headers)
+      unless request.is_a?(Net::HTTP::Get) || request.is_a?(Net::HTTP::Head)
+        request["Idempotency-Key"] ||= generate_idempotency_key
+      end
+
+      # TODO this is undocumented until we finalize it
+      additional_headers.each { |header, v| request[header] = v } if additional_headers
+    end
+
+    # from https://github.com/rails/rails/blob/6-0-stable/activesupport/lib/active_support/core_ext/securerandom.rb
+    def generate_idempotency_key(n = 16)
+      SecureRandom.random_bytes(n).unpack("C*").map do |byte|
+        idx = byte % 64
+        idx = SecureRandom.random_number(36) if idx >= 36
+        BASE36_ALPHABET[idx]
+      end.join
     end
 
-    def handle_response!(request, faraday_resp)
-      response = HTTP::Response.new(faraday_resp, request)
-      raise_api_error!(response) unless (200...300).include?(response.status)
+    def set_http_options(http, options)
+      http.open_timeout = options[:open_timeout] || 20
+      http.read_timeout = options[:read_timeout] || 60
+    end
+
+    def handle_response!(request, http_response)
+      response = HTTP::Response.new(http_response, request)
+      raise_api_error!(http_response, response) unless http_response.kind_of?(Net::HTTPSuccess)
       resource = if response.body
-          if BINARY_TYPES.include?(response.content_type)
+          if http_response.content_type&.include?(JSON_CONTENT_TYPE)
+            JSONParser.parse(self, response.body)
+          elsif BINARY_TYPES.include?(http_response.content_type)
             FileParser.parse(response.body)
           else
-            JSONParser.parse(self, response.body)
+            raise Recurly::Errors::InvalidResponseError, "Unexpected content type: #{http_response.content_type}"
           end
         else
           Resources::Empty.new
@@ -139,46 +249,34 @@ module Recurly
       resource
     end
 
-    def raise_network_error!(ex)
-      error_class = case ex
-        when Faraday::TimeoutError
-          Errors::TimeoutError
-        when Faraday::ConnectionFailed
-          Errors::ConnectionFailedError
-        when Faraday::SSLError
-          Errors::SSLError
-        else
-          Errors::NetworkError
-        end
+    def raise_api_error!(http_response, response)
+      if response.content_type.include?(JSON_CONTENT_TYPE)
+        error = JSONParser.parse(self, response.body)
+        error_class = Errors::APIError.error_class(error.type)
+        raise error_class.new(response, error)
+      end
 
-      raise error_class, ex.message
-    end
+      error_class = Errors::APIError.from_response(http_response)
 
-    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)
+      if error_class <= Recurly::Errors::APIError
+        error = Recurly::Resources::Error.new(message: "#{http_response.code}: #{http_response.message}")
+        raise error_class.new(response, error)
+      else
+        raise error_class, "#{http_response.code}: #{http_response.message}"
+      end
     end
 
     def read_headers(response)
       if !@_ignore_deprecation_warning && response.headers["Recurly-Deprecated"]&.upcase == "TRUE"
-        puts "[recurly-client-ruby] WARNING: Your current API version \"#{api_version}\" is deprecated and will be sunset on #{response.headers["Recurly-Sunset-Date"]}"
+        log_warn("DEPRECTATION WARNING", message: "Your current API version \"#{api_version}\" is deprecated and will be sunset on #{response.headers["Recurly-Sunset-Date"]}")
       end
       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)
+    def validate_path_parameters!(**options)
+      # Check to see that we are passing the correct data types
+      # This prevents a confusing error if the user passes in a non-primitive by mistake
       options.each do |k, v|
-        # Check to see that we are passing the correct data types
-        # This prevents a confusing error if the user passes in a non-primitive by mistake
         unless [String, Symbol, Integer, Float].include?(v.class)
           message = "We cannot build the url with the given argument #{k}=#{v.inspect}."
           if k =~ /_id$/
@@ -186,6 +284,17 @@ module Recurly
           end
           raise ArgumentError, message
         end
+      end
+      # Check to make sure that parameters are not empty string values
+      empty_strings = options.select { |_, v| v.is_a?(String) && v.strip.empty? }
+      if empty_strings.any?
+        raise ArgumentError, "#{empty_strings.keys.join(", ")} cannot be an empty string"
+      end
+    end
+
+    def interpolate_path(path, **options)
+      validate_path_parameters!(options)
+      options.each do |k, v|
         # We need to encode the values for the url
         options[k] = ERB::Util.url_encode(v.to_s)
       end
@@ -201,42 +310,37 @@ module Recurly
       end
     end
 
-    def scope_by_site(path, **options)
-      if site = site_id || options[:site_id]
-        "/sites/#{site}#{path}"
+    def set_api_key(api_key)
+      @api_key = api_key
+    end
+
+    def build_url(path, options)
+      path = scope_by_site(path, options)
+      if options.any?
+        "#{path}?#{URI.encode_www_form(options)}"
       else
         path
       end
     end
 
-    def set_faraday_connection(api_key)
-      options = {
-        url: BASE_URL,
-        request: { timeout: 60, open_timeout: 50 },
-        ssl: { verify: true },
-      }
-      # 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")
-        options[:ssl][:ca_file] = File.join(File.dirname(__FILE__), "../data/ca-certificates.crt")
+    def scope_by_site(path, **options)
+      if site = site_id || options[:site_id]
+        # Ensure that we are only including the site_id once because the Pager operations
+        # will use the cursor returned from the API which may already have these components
+        path.start_with?("/sites/#{site}") ? path : "/sites/#{site}#{path}"
+      else
+        path
       end
+    end
 
-      @conn = Faraday.new(options) do |faraday|
-        if [Logger::DEBUG, Logger::INFO].include?(@log_level)
-          faraday.response :logger
+    # Define a private `log_<level>` method for each log level
+    LOG_LEVELS.each do |level|
+      define_method "log_#{level}" do |tag, **attrs|
+        @logger.send(level, "Recurly") do
+          msg = attrs.each_pair.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+          "[#{tag}] #{msg}"
         end
-        faraday.basic_auth(api_key, "")
-        configure_net_adapter(faraday)
       end
     end
-
-    def set_options(options)
-      @log_level = options[:log_level] || Logger::WARN
-      @logger = Logger.new(STDOUT)
-      @logger.level = @log_level
-
-      # TODO this is undocumented until we finalize it
-      @extra_headers = options[:headers] || {}
-    end
   end
 end

data/lib/recurly/client/operations.rb

@@ -30,6 +30,7 @@ module Recurly
     #   order. In descending order updated records will move behind the cursor and could
     #   prevent some records from being returned.
     #
+    # @param state [String] Filter by state.
     # @return [Pager<Resources::Site>] A list of sites.
     # @example
     #   sites = @client.list_sites(limit: 200)
@@ -48,6 +49,16 @@ module Recurly
     #
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::Site] A site.
+    # @example
+    #   begin
+    #     site = @client.get_site(site_id: site_id)
+    #     puts "Got Site #{site}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def get_site(site_id:)
       path = interpolate_path("/sites/{site_id}", site_id: site_id)
       get(path)
@@ -251,6 +262,28 @@ module Recurly
     # @param body [Requests::AccountAcquisitionUpdatable] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::AccountAcquisitionUpdatable}
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::AccountAcquisition] An account's updated acquisition data.
+    # @example
+    #   begin
+    #     acquisition_update = {
+    #       campaign: "podcast-marketing",
+    #       channel: "social_media",
+    #       subchannel: "twitter",
+    #       cost: {
+    #         currency: "USD",
+    #         amount: 0.50
+    #       }
+    #     }
+    #     acquisition = @client.update_account_acquisition(
+    #       account_id: account_id,
+    #       body: acquisition_update
+    #     )
+    #     puts "Updated AccountAcqusition #{acquisition}"
+    #   rescue Recurly::Errors::ValidationError => e
+    #     # If the request was invalid, you may want to tell your user
+    #     # why. You can find the invalid params and reasons in e.recurly_error.params
+    #     puts "ValidationError: #{e.recurly_error.params}"
+    #   end
+    #
     def update_account_acquisition(account_id:, body:, **options)
       path = interpolate_path("/accounts/{account_id}/acquisition", account_id: account_id)
       put(path, body, Requests::AccountAcquisitionUpdatable, **options)
@@ -845,6 +878,26 @@ module Recurly
     # @param body [Requests::ShippingAddressCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::ShippingAddressCreate}
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::ShippingAddress] Returns the new shipping address.
+    # @example
+    #   begin
+    #     shipping_address_create = {
+    #       nickname: 'Work',
+    #       street1: '900 Camp St',
+    #       city: 'New Orleans',
+    #       region: 'LA',
+    #       country: 'US',
+    #       postal_code: '70115',
+    #       first_name: 'Joanna',
+    #       last_name: 'Du Monde'
+    #     }
+    #     shipping_address = @client.create_shipping_address(account_id: account_id, body: shipping_address_create)
+    #     puts "Created Shipping Address #{shipping_address}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def create_shipping_address(account_id:, body:, **options)
       path = interpolate_path("/accounts/{account_id}/shipping_addresses", account_id: account_id)
       post(path, body, Requests::ShippingAddressCreate, **options)
@@ -1230,11 +1283,46 @@ module Recurly
     # @param body [Requests::CouponUpdate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::CouponUpdate}
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::Coupon] The updated coupon.
+    # @example
+    #   begin
+    #     coupon_update = {
+    #       name: "New Coupon Name"
+    #     }
+    #     coupon = @client.update_coupon(coupon_id: coupon_id, body: coupon_update)
+    #     puts "Updated Coupon #{coupon}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def update_coupon(coupon_id:, body:, **options)
       path = interpolate_path("/coupons/{coupon_id}", coupon_id: coupon_id)
       put(path, body, Requests::CouponUpdate, **options)
     end
 
+    # Expire a coupon
+    #
+    # {https://developers.recurly.com/api/v2019-10-10#operation/deactivate_coupon deactivate_coupon api documenation}
+    #
+    # @param coupon_id [String] Coupon ID or code. For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-10off+.
+    # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
+    # @return [Resources::Coupon] The expired Coupon
+    # @example
+    #   begin
+    #     coupon = @client.deactivate_coupon(coupon_id: coupon_id)
+    #     puts "Deactivated Coupon #{coupon}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
+    def deactivate_coupon(coupon_id:, **options)
+      path = interpolate_path("/coupons/{coupon_id}", coupon_id: coupon_id)
+      delete(path, **options)
+    end
+
     # List unique coupon codes associated with a bulk coupon
     #
     # {https://developers.recurly.com/api/v2019-10-10#operation/list_unique_coupon_codes list_unique_coupon_codes api documenation}
@@ -1361,6 +1449,18 @@ module Recurly
     # @param custom_field_definition_id [String] Custom Field Definition ID
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::CustomFieldDefinition] An custom field definition.
+    # @example
+    #   begin
+    #     custom_field_definition = @client.get_custom_field_definition(
+    #       custom_field_definition_id: custom_field_definition_id
+    #     )
+    #     puts "Got Custom Field Definition #{custom_field_definition}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def get_custom_field_definition(custom_field_definition_id:, **options)
       path = interpolate_path("/custom_field_definitions/{custom_field_definition_id}", custom_field_definition_id: custom_field_definition_id)
       get(path, **options)
@@ -1615,6 +1715,20 @@ module Recurly
     # @param body [Requests::InvoiceUpdatable] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::InvoiceUpdatable}
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::Invoice] An invoice.
+    # @example
+    #   begin
+    #     invoice_update = {
+    #       customer_notes: "New Notes",
+    #       terms_and_conditions: "New Terms and Conditions"
+    #     }
+    #     invoice = @client.put_invoice(invoice_id: invoice_id, body: invoice_update)
+    #     puts "Updated invoice #{invoice}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def put_invoice(invoice_id:, body:, **options)
       path = interpolate_path("/invoices/{invoice_id}", invoice_id: invoice_id)
       put(path, body, Requests::InvoiceUpdatable, **options)
@@ -1741,11 +1855,34 @@ module Recurly
     # @param invoice_id [String] Invoice ID or number. For ID no prefix is used e.g. +e28zov4fw0v2+. For number use prefix +number-+, e.g. +number-1000+.
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::Invoice] The updated invoice.
+    # @example
+    #   begin
+    #     invoice = @client.void_invoice(invoice_id: invoice_id)
+    #     puts "Voided invoice #{invoice}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def void_invoice(invoice_id:, **options)
       path = interpolate_path("/invoices/{invoice_id}/void", invoice_id: invoice_id)
       put(path, **options)
     end
 
+    # Record an external payment for a manual invoices.
+    #
+    # {https://developers.recurly.com/api/v2019-10-10#operation/record_external_transaction record_external_transaction api documenation}
+    #
+    # @param invoice_id [String] Invoice ID or number. For ID no prefix is used e.g. +e28zov4fw0v2+. For number use prefix +number-+, e.g. +number-1000+.
+    # @param body [Requests::ExternalTransaction] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::ExternalTransaction}
+    # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
+    # @return [Resources::Transaction] The recorded transaction.
+    def record_external_transaction(invoice_id:, body:, **options)
+      path = interpolate_path("/invoices/{invoice_id}/transactions", invoice_id: invoice_id)
+      post(path, body, Requests::ExternalTransaction, **options)
+    end
+
     # List an invoice's line items
     #
     # {https://developers.recurly.com/api/v2019-10-10#operation/list_invoice_line_items list_invoice_line_items api documenation}
@@ -1780,6 +1917,15 @@ module Recurly
     # @param type [String] Filter by type field.
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Pager<Resources::LineItem>] A list of the invoice's line items.
+    # @example
+    #   line_items = @client.list_invoice_line_items(
+    #     invoice_id: invoice_id,
+    #     limit: 200
+    #   )
+    #   line_items.each do |line_item|
+    #     puts "Line Item: #{line_item.id}"
+    #   end
+    #
     def list_invoice_line_items(invoice_id:, **options)
       path = interpolate_path("/invoices/{invoice_id}/line_items", invoice_id: invoice_id)
       pager(path, **options)
@@ -1835,6 +1981,15 @@ module Recurly
     # @param invoice_id [String] Invoice ID or number. For ID no prefix is used e.g. +e28zov4fw0v2+. For number use prefix +number-+, e.g. +number-1000+.
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Pager<Resources::Invoice>] A list of the credit or charge invoices associated with the invoice.
+    # @example
+    #   invoices = @client.list_related_invoices(
+    #     invoice_id: invoice_id,
+    #     limit: 200
+    #   )
+    #   invoices.each do |invoice|
+    #     puts "Invoice: #{invoice.number}"
+    #   end
+    #
     def list_related_invoices(invoice_id:, **options)
       path = interpolate_path("/invoices/{invoice_id}/related_invoices", invoice_id: invoice_id)
       pager(path, **options)
@@ -1903,6 +2058,14 @@ module Recurly
     # @param type [String] Filter by type field.
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Pager<Resources::LineItem>] A list of the site's line items.
+    # @example
+    #   line_items = @client.list_line_items(
+    #     limit: 200
+    #   )
+    #   line_items.each do |line_item|
+    #     puts "LineItem: #{line_item.id}"
+    #   end
+    #
     def list_line_items(**options)
       path = interpolate_path("/line_items")
       pager(path, **options)
@@ -2065,6 +2228,19 @@ module Recurly
     # @param body [Requests::PlanUpdate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::PlanUpdate}
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::Plan] A plan.
+    # @example
+    #   begin
+    #     plan_update = {
+    #       name: "Monthly Kombucha Subscription"
+    #     }
+    #     plan = @client.update_plan(plan_id: plan_id, body: plan_update)
+    #     puts "Updated plan #{plan}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def update_plan(plan_id:, body:, **options)
       path = interpolate_path("/plans/{plan_id}", plan_id: plan_id)
       put(path, body, Requests::PlanUpdate, **options)
@@ -2077,6 +2253,16 @@ module Recurly
     # @param plan_id [String] Plan ID or code. For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-gold+.
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::Plan] Plan deleted
+    # @example
+    #   begin
+    #     plan = @client.remove_plan(plan_id: plan_id)
+    #     puts "Removed plan #{plan}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def remove_plan(plan_id:, **options)
       path = interpolate_path("/plans/{plan_id}", plan_id: plan_id)
       delete(path, **options)
@@ -2136,6 +2322,27 @@ module Recurly
     # @param body [Requests::AddOnCreate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::AddOnCreate}
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::AddOn] An add-on.
+    # @example
+    #   begin
+    #     new_add_on = {
+    #       code: 'coffee_grinder',
+    #       name: 'A quality grinder for your beans',
+    #       default_quantity: 1,
+    #       currencies: [
+    #         {
+    #           currency: 'USD',
+    #           unit_amount: 10_000
+    #         }
+    #       ]
+    #     }
+    #     add_on = @client.create_plan_add_on(plan_id: plan_id, body: new_add_on)
+    #     puts "Created plan add-on #{add_on}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def create_plan_add_on(plan_id:, body:, **options)
       path = interpolate_path("/plans/{plan_id}/add_ons", plan_id: plan_id)
       post(path, body, Requests::AddOnCreate, **options)
@@ -2175,6 +2382,23 @@ module Recurly
     # @param body [Requests::AddOnUpdate] The Hash representing the JSON request to send to the server. It should conform to the schema of {Requests::AddOnUpdate}
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::AddOn] An add-on.
+    # @example
+    #   begin
+    #     add_on_update = {
+    #       name: "A quality grinder for your finest beans"
+    #     }
+    #     add_on = @client.update_plan_add_on(
+    #       plan_id: plan_id,
+    #       add_on_id: add_on_id,
+    #       body: add_on_update
+    #     )
+    #     puts "Updated add-on #{add_on}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def update_plan_add_on(plan_id:, add_on_id:, body:, **options)
       path = interpolate_path("/plans/{plan_id}/add_ons/{add_on_id}", plan_id: plan_id, add_on_id: add_on_id)
       put(path, body, Requests::AddOnUpdate, **options)
@@ -2188,6 +2412,19 @@ module Recurly
     # @param add_on_id [String] Add-on ID or code. For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-gold+.
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::AddOn] Add-on deleted
+    # @example
+    #   begin
+    #     add_on = @client.remove_plan_add_on(
+    #       plan_id: plan_id,
+    #       add_on_id: add_on_id
+    #     )
+    #     puts "Removed add-on #{add_on}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def remove_plan_add_on(plan_id:, add_on_id:, **options)
       path = interpolate_path("/plans/{plan_id}/add_ons/{add_on_id}", plan_id: plan_id, add_on_id: add_on_id)
       delete(path, **options)
@@ -2224,6 +2461,14 @@ module Recurly
     # @param state [String] Filter by state.
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Pager<Resources::AddOn>] A list of add-ons.
+    # @example
+    #   add_ons = @client.list_add_ons(
+    #     limit: 200
+    #   )
+    #   add_ons.each do |add_on|
+    #     puts "AddOn: #{add_on.code}"
+    #   end
+    #
     def list_add_ons(**options)
       path = interpolate_path("/add_ons")
       pager(path, **options)
@@ -2236,6 +2481,16 @@ module Recurly
     # @param add_on_id [String] Add-on ID or code. For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-gold+.
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Resources::AddOn] An add-on.
+    # @example
+    #   begin
+    #     add_on = @client.get_add_on(add_on_id: add_on_id)
+    #     puts "Got add-on #{add_on}"
+    #   rescue Recurly::Errors::NotFoundError
+    #     # If the resource was not found, you may want to alert the user or
+    #     # just return nil
+    #     puts "Resource Not Found"
+    #   end
+    #
     def get_add_on(add_on_id:, **options)
       path = interpolate_path("/add_ons/{add_on_id}", add_on_id: add_on_id)
       get(path, **options)
@@ -2271,6 +2526,14 @@ module Recurly
     #
     # @param site_id [String] Site ID or subdomain. For ID no prefix is used e.g. +e28zov4fw0v2+. For subdomain use prefix +subdomain-+, e.g. +subdomain-recurly+.
     # @return [Pager<Resources::ShippingMethod>] A list of the site's shipping methods.
+    # @example
+    #   shipping_methods = @client.list_shipping_methods(
+    #     limit: 200
+    #   )
+    #   shipping_methods.each do |shipping_method|
+    #     puts "Shipping Method: #{shipping_method.code}"
+    #   end
+    #
     def list_shipping_methods(**options)
       path = interpolate_path("/shipping_methods")
       pager(path, **options)