recurly 3.5.0 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cb7459191e21c44fd4796091c9aba791fbc079c446aad569513bc3df26e5f10
-  data.tar.gz: 632a9ff4168fbdeeff508dc643920bf2290d225eaed28d5c7d0d92897495a26a
+  metadata.gz: 1ac32fad822fa602a4eae953b306b78bac66aea6a7bc67f1161df49fe72f813f
+  data.tar.gz: c5ae0c45581474a6f1ff9d996e0af49140073b5282585fb0af8daf34cde549c8
 SHA512:
-  metadata.gz: 7981c548326df5a65652e8184410a959927ad0b0630c1da6f286965389bb27a71a3da51e7e9804589b3564a94a4e266fc54f686eca3cd6d1b0aa6af779c73694
-  data.tar.gz: 10b42ef5247e4ecad7112c8b9ca9f2e8cbee81bacc4c55a773e1e4d1bcdec42cf4f01847a83c6975f46f9d5c86bba9bdd97d4f0b10710f891be1be0f2c2ab437
+  metadata.gz: 4bb163f9b5db0561aa52875398b33c1751608321cddf49c4337205175fb08f40f448853f7c1815f147a2c0a433692b4065993c9fadb6f61c0f1ce528887c1e5d
+  data.tar.gz: 2d2449562b1e0fdea4dfcd5d5eac1885bcff3f3bc3d1333fa0bc855eddcf584b8527807d6954bde7cfc2b10c151216e5bbcc79851c42842870a2de1aa61d402b

data/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.5.0
+current_version = 3.6.0
 parse = (?P<major>\d+)
 	\.(?P<minor>\d+)
 	\.(?P<patch>\d+)
@@ -10,3 +10,7 @@ serialize =
 
 [bumpversion:file:lib/recurly/version.rb]
 
+[bumpversion:file:GETTING_STARTED.md]
+parse = (?P<major>\d+)\.(?P<minor>\d+)
+serialize = {major}.{minor}
+

data/CHANGELOG.md

@@ -1,8 +1,25 @@
 # Changelog
 
-## [3.5.0](https://github.com/recurly/recurly-client-ruby/tree/HEAD)
+## [3.6.0](https://github.com/recurly/recurly-client-ruby/tree/HEAD)
 
-[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.4.1...HEAD)
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.5.0...HEAD)
+
+**Implemented enhancements:**
+
+- Latest Features [\#592](https://github.com/recurly/recurly-client-ruby/pull/592) ([bhelx](https://github.com/bhelx))
+- Support the programmer passing their own logger [\#590](https://github.com/recurly/recurly-client-ruby/pull/590) ([bhelx](https://github.com/bhelx))
+
+**Merged pull requests:**
+
+- Release 3.6.0 [\#594](https://github.com/recurly/recurly-client-ruby/pull/594) ([bhelx](https://github.com/bhelx))
+- Better format error message [\#593](https://github.com/recurly/recurly-client-ruby/pull/593) ([bhelx](https://github.com/bhelx))
+- Let bump2version manage the getting started doc [\#591](https://github.com/recurly/recurly-client-ruby/pull/591) ([bhelx](https://github.com/bhelx))
+- Document `Pager#first` and `Pager#count` [\#589](https://github.com/recurly/recurly-client-ruby/pull/589) ([bhelx](https://github.com/bhelx))
+- Ensure that path parameters are not empty strings [\#587](https://github.com/recurly/recurly-client-ruby/pull/587) ([douglasmiller](https://github.com/douglasmiller))
+
+## [3.5.0](https://github.com/recurly/recurly-client-ruby/tree/3.5.0) (2020-04-20)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/3.4.1...3.5.0)
 
 **Implemented enhancements:**
 

data/GETTING_STARTED.md

@@ -5,7 +5,7 @@ This repository houses the official ruby client for Recurly's V3 API.
 In your Gemfile, add `recurly` as a dependency.
 
 ```ruby
-gem 'recurly', '~> 3.2'
+gem 'recurly', '~> 3.6'
 ```
 
 > *Note*: We try to follow [semantic versioning](https://semver.org/) and will only apply breaking changes to major versions.
@@ -41,6 +41,27 @@ client = Recurly::Client.new(api_key: API_KEY2)
 sub = client.get_subscription(subscription_id: 'abcd7890')
 ```
 
+## Logging
+
+The client constructor optionally accepts a logger provided by the programmer. The logger you pass should be an instance of ruby stdlib's [Logger](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html)
+or follow the same interface. By default, the client creates a logger to `STDOUT` with level `WARN`.
+
+```ruby
+require 'logger'
+
+# Create a logger to STDOUT
+logger = Logger.new(STDOUT)
+logger.level = Logger::INFO
+
+# You could also use an existing logger
+# If you are using Rails you may want to use your application's logger
+logger = Rails.logger
+
+client = Recurly::Client.new(api_key: API_KEY, logger: logger)
+```
+
+> *SECURITY WARNING*: The log level should never be set to DEBUG in production. This could potentially result in sensitive data in your logging system.
+
 # Operations
 
 The {Recurly::Client} contains every `operation` you can perform on the site as a list of methods. Each method is documented explaining
@@ -109,6 +130,45 @@ end
 `limit` defaults to 20 items per page and can be set from 1 to 200. Choosing a lower limit means more network requests but smaller payloads.
 We recommend keeping the default for most cases but increasing the limit if you are planning on iterating through many pages of items (e.g. all transactions in your site).
 
+## Efficiently Fetch the First or Last Resource
+
+The Pager class implements a first method which allows you to fetch just the first or last resource from the server. On top of being a convenient abstraction, this is implemented efficiently by only asking the server for the 1 item you want.
+
+```ruby
+accounts = client.list_accounts(
+  subscriber: true,
+  order: :desc
+)
+
+last_subscriber = accounts.first
+```
+
+If you want to fetch the last account in this scenario, invert the order from descending `desc` to ascending `asc`:
+
+```ruby
+accounts = client.list_accounts(
+  subscriber: true,
+  order: :asc
+)
+
+first_subscriber = accounts.first
+```
+
+## Counting Resources
+
+The Pager class implements a `count` method which allows you to count the resources the pager would return. It does so by calling the endpoint with `HEAD` and parsing and returning the `Recurly-Total-Records` header. This method respects any filtering parameters you apply to the pager, but the sorting parameters will have no effect.
+
+```ruby
+accounts = client.list_accounts(
+  subscriber: true,
+  begin_time: DateTime.new(2017,1,1)
+)
+
+# Calling count here will return an integer indicating
+# the number of subscribers since 2017
+count = accounts.count
+# => 573
+```
 
 # Creating Resources
 

data/lib/recurly/client.rb

@@ -15,11 +15,11 @@ module Recurly
     CA_FILE = File.join(File.dirname(__FILE__), "../data/ca-certificates.crt")
     BINARY_TYPES = [
       "application/pdf",
-    ]
+    ].freeze
     JSON_CONTENT_TYPE = "application/json"
     MAX_RETRIES = 3
-
-    BASE36_ALPHABET = ("0".."9").to_a + ("a".."z").to_a
+    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.
     #
@@ -45,12 +45,31 @@ 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_api_key(api_key)
-      set_options(options)
+
+      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?
@@ -100,7 +119,6 @@ module Recurly
       if request_data
         request_class.new(request_data).validate!
         json_body = JSON.dump(request_data)
-        logger.info("PUT BODY #{json_body}")
         request.body = json_body
       end
       http_response = run_request(request, options)
@@ -116,9 +134,6 @@ module Recurly
 
     private
 
-    # @return [Logger]
-    attr_reader :logger
-
     @connection_pool = Recurly::ConnectionPool.new
 
     class << self
@@ -134,14 +149,37 @@ module Recurly
 
         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
@@ -190,8 +228,6 @@ module Recurly
     def set_http_options(http, options)
       http.open_timeout = options[:open_timeout] || 20
       http.read_timeout = options[:read_timeout] || 60
-
-      http.set_debug_output(logger) if @log_level <= Logger::INFO && !http.started?
     end
 
     def handle_response!(request, http_response)
@@ -232,15 +268,15 @@ module Recurly
 
     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 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$/
@@ -248,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
@@ -286,10 +333,14 @@ module Recurly
       end
     end
 
-    def set_options(options)
-      @log_level = options[:log_level] || Logger::WARN
-      @logger = Logger.new(STDOUT)
-      @logger.level = @log_level
+    # 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
+      end
     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,6 +1283,19 @@ 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)
@@ -1242,6 +1308,16 @@ module Recurly
     # @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)
@@ -1373,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)
@@ -1627,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)
@@ -1753,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}
@@ -1792,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)
@@ -1847,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)
@@ -1915,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)
@@ -2077,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)
@@ -2089,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)
@@ -2148,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)
@@ -2187,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)
@@ -2200,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)
@@ -2236,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)
@@ -2248,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)
@@ -2283,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)