tribune_recurly_api 0.4.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b9eafd5553b067ea352e854a202c773f0565c728b0fd89c1b8775702f36ee29
-  data.tar.gz: 73269fbd07f54d384a52a04bdc3602c1162386cf942763e2becd16b336a728a9
+  metadata.gz: 90bc9314bc9a69973358b2865c2f75c5d4ce83f17393304deec39e8dae4dc2d4
+  data.tar.gz: 44ba860e9260009fb54fc277fc7418b5da1325d4d304dff30f7fe247b544450c
 SHA512:
-  metadata.gz: 0765af740d352b35433b5fe4b0ab2b4b0c19428b776c4f69c42dac223f7290d839dc1c4a0345f4cbb53d057d306250ed94708f6743df027d6f16fc227b95015f
-  data.tar.gz: cb56612cea6cd6584ecbaae4c31d31d3935167dc7b31c71abd1be887b6fde12b2cbc26b664ad4ecb7ba923b575c2a09bf00915ef1ba28eaf012b270e7bb0baf2
+  metadata.gz: 8a526bdd23c232b57019d4f5bd8356781cbfd696efd32fef9baefabda89d3b469261dc8ad1e3a313548f269d517e29f8f81a95e5a30a53fd285bfdae20f3adba
+  data.tar.gz: 5bfccbbc08e4fdb9edf9a972dade04955d92094af277546eff4698a55e67220e8fa1e2e0dbe8b60e05b4677175f80818c225284da9da8726d532d7c064debcb8

data/lib/recurly_api.rb

@@ -1,22 +1,8 @@
-# frozen_string_literal: true
-
-require 'recurly_api/version'
-require 'recurly_api/client'
-# some info goes here..
-module RecurlyApi
-  class Error < StandardError; end
-
-  # RecurlyApi.logger.debug("I'm a debug log")
-  # logger.info("I'm an info log")
-  # logger.warn("I'm a warn log")
-  # logger.error("I'm an error log: error message")
-  # logger.fatal("I'm a fatal log")
-  def self.logger
-    # @@logger ||= defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
-    @@logger ||= Logger.new(STDOUT)
-  end
-
-  def self.logger=(logger)
-    @@logger = logger
-  end
-end
+# frozen_string_literal: true
+
+require 'recurly_api/version'
+require 'recurly_api/client'
+# some info goes here..
+module RecurlyApi
+  class Error < StandardError; end
+end

data/lib/recurly_api/caching.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Perform caching for Recurly Responses( only for GET requests)
+module RecurlyApi
+  # Don't perform caching for non-rails projects
+  module Caching
+    # accessor for getter and setter methods
+    attr_accessor :ignore_caching, # skip/bypass caching true|false
+                  :cache_expires_in,
+                  :cache_key # key name to read/write cache, # default value is caller method_name
+
+    # default settings for caching, every GET request is cached by default with default expiry_time 5.seconds
+    CACHE_SETTINGS = { bypass: false,
+                       expiry_time_in_secs: 60 }.freeze
+
+    # Usage examples to perform caching in RecurlyApi:Client
+    # cache.write('key', 'val', expires_in: 30)
+    # cache.fetch('key')
+    def cache
+      @cache ||= defined?(Rails) ? Rails.cache : nil
+    end
+
+    # for non-rails applications do not perform caching on Recurly Response's
+    # perform caching only if it is enabled in Rails application
+    def caching_enabled?
+      !cache.nil? && Rails.application.config.action_controller.perform_caching
+    end
+
+    # tribune_recurly_api GEM related cache saved as 'tribune_recurly_api.<cache_key>' in cache_store
+    def cache_prefix_name
+      'tribune_recurly_api.'
+    end
+
+    def cache_key_with_prefix
+      "#{cache_prefix_name}#{cache_key}"
+    end
+
+    def ignore_caching?
+      @ignore_caching
+    end
+    alias bypass_caching? ignore_caching? # both are same
+
+    def write_final_resp_to_cache
+      cache.write(cache_key_with_prefix, final_response, expires_in: cache_expires_in)
+    end
+
+    def fetch_response_from_cache
+      # cache.exist?(cache_key_with_prefix) # check if cache already exists or not for requested API call
+      cache.fetch(cache_key_with_prefix) # returns nil if cache not exists for requested API call.
+    end
+
+    # TODO: remove below method once integration testing is done
+    def check_logs_for_caching_info
+      logger.info("#{logger_heading}: ----> caching_enabled?: #{caching_enabled?}")
+      # logger.info("#{logger_heading}: ----> ignore_caching?: #{ignore_caching?}")
+      logger.info("#{logger_heading}: ----> bypass_caching?: #{bypass_caching?}")
+      logger.info("#{logger_heading}: ----> http_method: #{http_method} -- #{http_method.class}")
+      logger.info("#{logger_heading}: ----> cache_expires_in: #{cache_expires_in}")
+      logger.info("#{logger_heading}: ----> cache_key: #{cache_key} -- #{cache_key.class}")
+      # logger.info("#{logger_heading}: ----> final response: #{final_response || fetch_response_from_cache}")
+      logger.info("#{logger_heading}: ----> ratelimit_retries: #{ratelimit_retries}")
+    end
+  end
+end

data/lib/recurly_api/client.rb

@@ -1,142 +1,183 @@
-# frozen_string_literal: true
-#
-require 'rest-client'
-require 'json'
-module RecurlyApi
-  # Wrapper class to connect Recurly API end-points
-  class Client
-    # Requesting API end-points
-    require_relative './client/accounts'
-    require_relative './client/plans'
-    require_relative './client/subscriptions'
-    require_relative './client/other_requests.rb'
-
-    API_DEFAULTS = { base_host: 'v3.recurly.com',
-                     api_version: 'v2021-02-25' }.freeze
-    # request for The number of records to return per page
-    RECORDS_LIMIT = 20
-    RATE_LIMIT_MAX_RETRIES = 3
-
-    attr_accessor :site_id, :authorization_key, :base_host,
-                  :api_version, :api_endpoint, :ratelimit_retries
-
-    # Initialize a client.
-    # KeyWord args are optional while initializing and defaults to the values present in recurly_config.yml,
-    # Ex: If you want to use custom 'api_version' instead predefined, initialize client as below,
-    #  rc = RecurlyApi::Client.new(api_version: 'v2019-10-10')
-    # @param authorization_key [String] Required, Recurly API auth key.
-    # @param site_id [String] Required, ex: 'subdomain-tribune' for https://tribune.recurly.com
-    # @param base_host [String] Optional, default: v3.recurly.com
-    # @param api_version [String] Optional, Recurly api_version ex: 'v2021-02-25' | 'v2019-10-10'
-    # @param ratelimit_retries [Integer] Optional, retry limit for rate limit exceeds, default: 3
-    def initialize(authorization_key: nil,
-                   site_id: nil,
-                   base_host: nil,
-                   api_version: nil,
-                   ratelimit_retries: RATE_LIMIT_MAX_RETRIES)
-      @authorization_key = authorization_key
-      @site_id = site_id
-      raise ArgumentError, "'authorization_key' must be set to a non-nil value" if @authorization_key.nil?
-      raise ArgumentError, "'site_id' must be set to a non-nil value" if @site_id.nil?
-
-      @base_host = base_host || API_DEFAULTS[:base_host]
-      @api_version = api_version || API_DEFAULTS[:api_version]
-      @api_endpoint = "https://#{@base_host}/sites/#{@site_id}"
-      @ratelimit_retries = ratelimit_retries
-    end
-
-    # request Recurly V3 API (v2021-02-25)(https://developers.recurly.com/api/v2021-02-25/)
-    # @param path [String] path for API call -> ex: 'plans/{plan_id}', 'accounts/{account_id}'.
-    # @param http_method [Symbol] request method -> ex:  get | post | put | delete.
-    # @param params [Hash] query parameters -> ex: { limit: 20, order: :asc etc }
-    # @param payload [Hash] request body parameters( for post, put etc..)
-    # @param add_headers [Hash] additional headers if any ex: User-Agent etc..
-    # RestClient retry { https://blog.appsignal.com/2018/05/16/ensure-retry-and-reraise-exceptions-in-ruby.html }
-    def request_api(path:, http_method: :get, params: {}, payload: {}, add_headers: {})
-      raise ArgumentError, "'request path' must be set to a non-nil value" if path.nil?
-
-      max_retries = ratelimit_retries # max count to retry if rate limit requests are exceeded.
-      retry_count = 0
-      delay = 1 # in seconds
-      end_point = "#{api_endpoint}/#{path}"
-      headers = ensure_request_headers(add_headers).merge!(params: params)
-      resp = RestClient::Request.execute(method: http_method,
-                                         url: end_point,
-                                         payload: payload.empty? ? payload : payload.to_json,
-                                         headers: headers)
-    rescue RestClient::ExceptionWithResponse => e
-      e.response
-    rescue RestClient::Exception => e
-      # Timed out reading data from server
-      e.response
-    rescue StandardError => e
-      raise e.message
-    else
-      begin
-        raise 'API Rate limit exceeded' if rate_limit_exceeded?(resp)
-      rescue StandardError => _e
-        RecurlyApi.logger.error "API Rate limit exceeded retrying again. Retries left: #{max_retries - retry_count}"
-        sleep delay += retry_count
-        retry_count += 1
-        retry if retry_count < max_retries
-      end
-      resp
-    end
-
-    def ensure_request_headers(add_headers)
-      accept_header = "application/vnd.recurly.#{api_version}+json"
-      { "Authorization": authorization_key,
-        "Content-Type": 'application/json',
-        accept: accept_header }.merge!(add_headers)
-    end
-
-    def handle_response!(resp, payload_name: :data, single_node: false)
-      if rate_limit_exceeded?(resp)
-        handle_rate_limit_exceed(resp)
-      else
-        json_body = JSON.parse(resp.body)
-        if json_body['error']
-          handle_error_response(resp.code, json_body)
-        else
-          { success: true, status: resp.code,
-            "#{payload_name}": single_node ? json_body : json_body['data'] }
-        end
-      end
-    end
-
-    def handle_error_response(code, json_body)
-      { success: false, status: code,
-        error: json_body['error']['type'],
-        message: json_body['error']['message'] }
-    end
-
-    # Recurly rate limiting
-    # { https://developers.recurly.com/api/v2019-10-10/#section/Getting-Started/Limits }
-    # The rate limit is calculated over a sliding 5 minute window.
-    # This means a production site could make 4,000 requests within one minute and not hit the rate limit
-    # so long as the site made less than 1,000 requests during the prior 4 minute
-    # --------------
-    # Response Headers that returned related to rate limiting by Recurly.
-    # x_ratelimit_limit: The maximum number of requests available in the current time frame(5-minite window)
-    # x_ratelimit_remaining: the number of requests left for the 5-minute window
-    # x_ratelimit_reset: the remaining window before the rate limit resets, in UNIX Epoch seconds
-
-    # Check if rate limit exceeded or not using resp status code OR x_ratelimit_remaining header
-    def rate_limit_exceeded?(resp)
-      ratelimit_remaining = resp.headers[:x_ratelimit_remaining]
-      resp.code.eql?(429) || (ratelimit_remaining && ratelimit_remaining.to_i < 1)
-    end
-
-    def handle_rate_limit_exceed(resp)
-      resp_headers = resp.headers
-      rate_limit_info = { limit: resp_headers[:x_ratelimit_limit],
-                          remaining: resp_headers[:x_ratelimit_remaining],
-                          reset_time_seconds: resp_headers[:x_ratelimit_reset],
-                          reset_time: DateTime.strptime(resp_headers[:x_ratelimit_reset], '%s') }
-      { success: false, status: 429,
-        error: 'Recurly API Rate limit exceeded',
-        message: 'Too Many Requests, See rate-limiting for more info',
-        rate_limit_info: rate_limit_info }
-    end
-  end
-end
+# frozen_string_literal: true
+
+require 'rest-client'
+require 'json'
+require 'recurly_api/logging'
+require 'recurly_api/exception_handler'
+require 'recurly_api/rate_limiting'
+require 'recurly_api/caching'
+module RecurlyApi
+  # Wrapper class to connect Recurly API end-points
+  # rubocop:disable Metrics/ClassLength
+  class Client
+    include Logging
+    include ExceptionHandler
+    include RateLimiting
+    include Caching
+
+    # Requesting API end-points
+    require_relative './client/accounts'
+    require_relative './client/plans'
+    require_relative './client/subscriptions'
+    require_relative './client/other_requests.rb'
+    API_DEFAULTS = { base_host: 'v3.recurly.com',
+                     api_version: 'v2021-02-25' }.freeze
+    # request for The number of records to return per page
+    RECORDS_LIMIT = 20
+
+    # Initialize method attributes
+    attr_accessor :site_id, :authorization_key, :base_host,
+                  :api_version, :api_endpoint
+    # request attributes for request_api method
+    attr_accessor :path_name, :http_method, :query_params,
+                  :payload, :additional_headers, :payload_name,
+                  :cache_key_name, :optional_params
+    # response attributes
+    attr_accessor :recurly_response, :final_response
+
+
+    # Initialize a client.
+    # KeyWord args are optional while initializing and defaults to the values present in recurly_config.yml(Rails only),
+    # Ex: If you want to use custom 'api_version' instead predefined, initialize client as below,
+    #  rc = RecurlyApi::Client.new(api_version: 'v2019-10-10')
+    # @param authorization_key [String] Required, Recurly API auth key.
+    # @param site_id [String] Required, ex: 'subdomain-tribune' for https://tribune.recurly.com
+    # @param base_host [String] Optional, default: v3.recurly.com
+    # @param api_version [String] Optional, Recurly api_version ex: 'v2021-02-25' | 'v2019-10-10'
+    # @param ratelimit_retries [Integer] Optional, retry limit for rate limit exceeds, default: 3
+    def initialize(authorization_key:,
+                   site_id:,
+                   base_host: nil,
+                   api_version: nil,
+                   ratelimit_retries: RATE_LIMIT_MAX_RETRIES)
+      @authorization_key = authorization_key
+      @site_id = site_id
+      raise ArgumentError, "'authorization_key' must be set to a non-nil value" if @authorization_key.nil?
+      raise ArgumentError, "'site_id' must be set to a non-nil value" if @site_id.nil?
+
+      @base_host = base_host || API_DEFAULTS[:base_host]
+      @api_version = api_version || API_DEFAULTS[:api_version]
+      @api_endpoint = "https://#{@base_host}/sites/#{@site_id}"
+      @ratelimit_retries = ratelimit_retries
+      @cache_expires_in = CACHE_SETTINGS[:expiry_time_in_secs]
+      @ignore_caching = CACHE_SETTINGS[:bypass]
+    end
+
+    # TODO: remove unnecessary logs once integration testing completed
+    # request Recurly V3 API (v2021-02-25)(https://developers.recurly.com/api/v2021-02-25/)
+    # @param path_name [String] Required, path for API call -> ex: 'plans/{plan_id}', 'accounts/{account_id}'.
+    # #@param http_method [Symbol] Optional, default: :get -> ex:  get | post | put | delete.
+    # @param query_params [Hash] Optional, Recurly query string parameters:
+    #      i. :ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #           commas as separators, e.g. <ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6>.
+    #     ii. :limit [Integer] Limit number of records 1-200.
+    #    iii. :order [String] Sort order.
+    #     iv: :sort [String] Sort field. You *really* only want to sort by <updated_at> in ascending
+    # @param additional_headers [Hash] Optional,  additional headers if any ex: User-Agent etc..
+    # @param payload [Hash] Optional, request body parameters( for post, put etc..)
+    # @param optional_params [Hash] Optional, or any of below ( ref full usage example)
+    #  :payload_name [Symbol] Optional, defaults to ':data'
+    #  :bypass_caching [Boolean] Optional, default value is false
+    #  :cache_expiry_in_secs [Integer] Optional, default value is 60 seconds
+
+    # Ful Usage Example: Below is the example for 'request_api' call that includes all options
+    #       res = request_api(path_name: 'plans', # required
+    #                         http_method: :get,  # optional, :post|put|patch|delete
+    #                         query_params: recurly_query_params, # optional
+    #                         payload: {}, # optional, request body params
+    #                         additional_headers: { 'User-Agent': 'abc', ..}, # optional
+    #                         cache_key_name: 'key123', # optional, defaults to method_name
+    #                         bypass_caching: true, # optionals, default false
+    #                         payload_name: 'list_all_plans', # optional defaults to caller method_name
+    #                         cache_expiry_in_secs: 180 # optional default 60
+    #                         )
+    # RestClient retry { https://blog.appsignal.com/2018/05/16/ensure-retry-and-reraise-exceptions-in-ruby.html }
+    # rubocop:disable Metrics/ParameterLists
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/PerceivedComplexity
+    def request_api(path_name:, http_method: :get, query_params: {},
+                    payload: {}, additional_headers: {},
+                    cache_key_name: nil, **optional_params)
+      raise ArgumentError, "'request path' must be set to a non-nil value" if path_name.nil?
+
+      self.path_name = path_name # set the HTTP Verb (caching is only done for HTTP GET requests)
+      self.http_method = http_method # set the HTTP Verb (caching is only done for HTTP GET requests)
+      self.query_params = query_params
+      self.payload = payload
+      self.additional_headers = additional_headers
+      self.cache_key_name = cache_key_name
+      self.optional_params = optional_params
+      # optional params ===>
+      self.payload_name = optional_params[:payload_name] || 'payload'
+      self.ignore_caching = optional_params[:bypass_caching] || ignore_caching
+      self.cache_expires_in = optional_params[:cache_expiry_in_secs] || cache_expires_in
+      # caller_method_name = caller_locations.first.label # Ruby 2.0 +
+      caller_method_name = caller(1..1).first[/`(.*)'/, 1] # Prior Ruby 2.0
+      self.cache_key = cache_key_name || caller_method_name # fallbacks to caller method if cache_key_name not present
+      # TODO: remove below method once integration testing is completed, also remove unnecessary logs
+      check_logs_for_caching_info
+      # Cashing related stuff... (caching is performed on response only on :get requests when it is enabled)
+      # by default Cache  bypassed for non rails applications
+      if caching_enabled? && !bypass_caching? && http_method.eql?(:get)
+        cached_response = fetch_response_from_cache
+        # Do NOT use a falsy check because we need to distinguish 'false' from 'nil'
+        if cached_response.nil?
+          fetch_response_from_recurly(cache_recurly_resp: true)
+        else
+          logger.info("#{logger_cache_heading}: response returned from cache store and key is: #{cache_key_with_prefix}")
+          cached_response
+        end
+      else
+        logger.warn("#{logger_cache_heading}: caching of Recurly Response completely bypassed")
+        fetch_response_from_recurly
+      end
+    end
+
+    def fetch_response_from_recurly(cache_recurly_resp: false)
+      # rescue/raise all your all exceptions in ExceptionHandler's method
+      recurly_api_exception_handler do
+        end_point = "#{api_endpoint}/#{path_name}"
+        headers = ensure_request_headers.merge!(params: query_params)
+        self.recurly_response = RestClient::Request.execute(method: http_method,
+                                                            url: end_point,
+                                                            payload: payload.empty? ? nil : payload.to_json,
+                                                            headers: headers)
+        self.final_response = handle_recurly_response!
+        retry_on_rate_limit_exceed
+        # don't cache rate_limit_exceed_response
+        if cache_recurly_resp && !rate_limit_exceeded?
+          write_final_resp_to_cache
+          logger.info("#{logger_cache_heading}: Recurly Response saved to cache_store with Key: #{cache_key_with_prefix}")
+        end
+        final_response
+      end
+    end
+
+    def ensure_request_headers
+      accept_header = "application/vnd.recurly.#{api_version}+json"
+      { "Authorization": authorization_key,
+        "Content-Type": 'application/json',
+        accept: accept_header }.merge!(additional_headers)
+    end
+
+    def handle_recurly_response!
+      if rate_limit_exceeded?
+        rate_limit_exceed_response
+      else
+        json_body = JSON.parse(recurly_response.body)
+        if json_body['error']
+          handle_error_response(recurly_response.code, json_body)
+        else
+          { success: true, status_code: recurly_response.code,
+            "#{payload_name}": json_body }
+        end
+      end
+    end
+
+    def handle_error_response(code, json_body)
+      { success: false, status_code: code,
+        error: json_body['error']['type'],
+        message: json_body['error']['message'] }
+    end
+  end
+end

data/lib/recurly_api/client/accounts.rb

@@ -1,25 +1,23 @@
-# frozen_string_literal: true
-
-module RecurlyApi
-  # API requests to fetch Accounts related data
-  class Client
-    # Fetch Account Info--
-    # { https://developers.recurly.com/api/v2021-02-25/index.html#operation/get_account }
-    # @param ssor_id [String] Required, Account ID(SsorID) or code.
-    # For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-bob+.
-    def account_info(ssor_id:)
-      resp = request_api(path: "accounts/#{ssor_id}")
-      handle_response!(resp, payload_name: :account_info, single_node: true)
-    end
-
-    # Deactivate account ---
-    # { https://developers.recurly.com/api/v2021-02-25/index.html#operation/deactivate_account }
-    # @param ssor_id [String] Required, Account ID(SsorID) or code.
-    # For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-bob+.
-    def deactivate_account(ssor_id:)
-      path = "accounts/#{ssor_id}"
-      resp = request_api(path: path, http_method: :delete)
-      handle_response!(resp, payload_name: :account_info, single_node: true)
-    end
-  end
-end
+# frozen_string_literal: true
+
+module RecurlyApi
+  # API requests to fetch Accounts related data
+  class Client
+    # Fetch Account Info--
+    # { https://developers.recurly.com/api/v2021-02-25/index.html#operation/get_account }
+    # @param ssor_id [String] Required, Account ID(SsorID) or code.
+    # For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-bob+.
+    def account_info(ssor_id:, **optional_params)
+      request_api(path_name: "accounts/#{ssor_id}", **optional_params) # cache_key_name: cache_key_name
+    end
+
+    # Deactivate account ---
+    # { https://developers.recurly.com/api/v2021-02-25/index.html#operation/deactivate_account }
+    # @param ssor_id [String] Required, Account ID(SsorID) or code.
+    # For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-bob+.
+    def deactivate_account(ssor_id:)
+      path = "accounts/#{ssor_id}"
+      request_api(path_name: path, http_method: :delete)
+    end
+  end
+end

data/lib/recurly_api/client/other_requests.rb

@@ -1,17 +1,16 @@
-# frozen_string_literal: true
-
-module RecurlyApi
-  # This class fetches the data of Recurly API end-points
-  class Client
-    # Show the coupon redemptions for an account --
-    # { https://developers.recurly.com/api/v2021-02-25/index.html#tag/coupon_redemption }
-    # @param ssor_id [String] Recurly Account ID(SsorID) or code.
-    # For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-bob+.
-    def coupon_redemptions(ssor_id:)
-      resp = request_api(path: "accounts/#{ssor_id}/coupon_redemptions")
-      handle_response!(resp, payload_name: :coupon_redemptions, single_node: true)
-    end
-
-    # Other request any.....
-  end
-end
+# frozen_string_literal: true
+
+module RecurlyApi
+  # This class fetches the data of Recurly API end-points
+  class Client
+    # Show the coupon redemptions for an account --
+    # { https://developers.recurly.com/api/v2021-02-25/index.html#tag/coupon_redemption }
+    # @param ssor_id [String] Recurly Account ID(SsorID) or code.
+    # For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-bob+.
+    def coupon_redemptions(ssor_id:, **optional_params)
+      request_api(path_name: "accounts/#{ssor_id}/coupon_redemptions", **optional_params)
+    end
+
+    # Other request any.....
+  end
+end

data/lib/recurly_api/client/plans.rb

@@ -1,32 +1,43 @@
-# frozen_string_literal: true
-
-module RecurlyApi
-  # API requests to fetch Plans related data
-  class Client
-    #  List a site's plans
-    # { https://developers.recurly.com/api/v2021-02-25/index.html#operation/list_plans }
-    # @param params [Hash] Optional query string parameters:
-    #        :ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #                      commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
-    #        :limit [Integer] Limit number of records 1-200.
-    #        :order [String] Sort order.
-    #        :sort [String] Sort field. You *really* only want to sort by +updated_at+ in ascending
-    # ex:
-    # params = { limit: 2, order: :asc, .....}
-    # ex: client.list_plans(params)
-    def list_plans(**params)
-      resp = request_api(path: 'plans', params: params)
-      # handle_response(resp, payload_name: :plans)
-      handle_response!(resp)
-    end
-
-    # Fetch Plan Info--
-    # { https://developers.recurly.com/api/v2021-02-25/index.html#operation/get_plan}
-    # @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+.
-    def plan_info(plan_id:)
-      resp = request_api(path: "plans/#{plan_id}")
-      handle_response!(resp, payload_name: :plan_info, single_node: true)
-    end
-  end
-end
+# frozen_string_literal: true
+
+module RecurlyApi
+  # API requests to fetch Plans related data
+  class Client
+    #  List a site's plans
+    # { https://developers.recurly.com/api/v2021-02-25/index.html#operation/list_plans }
+    # @param recurly_query_params [Hash] Optional, Recurly query string parameters:
+    #      i. :ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #           commas as separators, e.g. <ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6>.
+    #     ii. :limit [Integer] Limit number of records 1-200.
+    #    iii. :order [String] Sort order.
+    #     iv: :sort [String] Sort field. You *really* only want to sort by <updated_at> in ascending
+    # @param additional_headers [Hash] Optional,  additional headers if any ex: User-Agent etc..
+    # @param payload [Hash] Optional, request body parameters( for post, put etc..)
+    # @param optional_params [Hash] Optional, or any of below ( ref full usage example)
+    #  :payload_name [Symbol] Optional, defaults to caller method_name
+    #  :bypass_caching [Boolean] Optional, default value is false
+    #  :cache_expiry_in_secs [Integer] Optional, default value is 60 seconds
+
+    # Examples:
+    #  query_params = { limit: 2, order: :asc, ids: ['abc', 'def'..etc], :sort: <value>}
+    #  client.list_plans(recurly_query_params: query_params, bypass_cache: true)
+    #  client.list_plans(recurly_query_params: query_params, cache_expires_in: 120, payload_name: :fetch_plans)
+    # client.list_plans(recurly_query_params: query_params)
+
+    def list_plans(recurly_query_params: {}, **optional_params)
+      # payload_name = optional_params[:payload_name] # if not present default value is :payload
+      cache_key_name = 'list_all_plans' # optional by default cache_key is caller method_name in receiver i.e. list_plans here
+      request_api(path_name: 'plans', query_params: recurly_query_params,
+                  cache_key_name: cache_key_name, **optional_params)
+    end
+
+    # Fetch Plan Info--
+    # { https://developers.recurly.com/api/v2021-02-25/index.html#operation/get_plan}
+    # @param plan_id [String] Required, Plan ID or code.
+    #    - For ID no prefix is used e.g. <e28zov4fw0v2>. For code use prefix <code->, ex. <code-gold>.
+    # @param optional_params [Hash] Optional, same as above
+    def plan_info(plan_id:, **optional_params)
+      request_api(path_name: "plans/#{plan_id}", **optional_params) # cache_key_name: cache_key_name
+    end
+  end
+end

data/lib/recurly_api/client/subscriptions.rb

@@ -1,98 +1,94 @@
-# frozen_string_literal: true
-
-module RecurlyApi
-  # API requests to fetch Subscriptions related data
-  class Client
-    # Fetch Account Subscriptions ---
-    # { https://developers.recurly.com/api/v2019-10-10/index.html#operation/list_account_subscriptions }
-    # @param ssor_id [String] Account ID(SsorID) or code.
-    # For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-gold+.
-    # For SsorID no prefix is required
-    #  @param params [Hash] Optional query string parameters
-    def account_subscriptions(ssor_id:, **params)
-      path = "accounts/#{ssor_id}/subscriptions"
-      resp = request_api(path: path, params: params)
-      handle_response!(resp)
-    end
-
-    # Checking if user already has subscription OR
-    # Checking if user has a subscription for particular plan by its code
-    # ---------------
-    # @param ssor_id [String] required, Recurly Account Code(i.e SsorID)
-    # @prams plan_code [String] optional,
-    #    - if present then checks if user has subscription for that particular plan by its code
-    # Usage ex:
-    # client.check_user_subscription(ssor_id: '4900-0272-6875', plan_code: '000150d03d')
-    # response => { :success=>true, :status=>200, :has_subscription=>true }
-    def check_user_subscription(ssor_id:, plan_code: nil)
-      resp = account_subscriptions(ssor_id: "code-#{ssor_id}")
-      if resp[:success]
-        has_subscription = false
-        subs = resp[:data]
-        has_subscription = true if subs.any?
-        if plan_code
-          sub =  subs.detect { |s| s['plan']['code'].eql?(plan_code) }
-          has_subscription = sub ? true : false
-        end
-        { success: true, status: 200, has_subscription: has_subscription }
-      else
-        resp
-      end
-    end
-
-    # List a site's subscriptions
-    # { https://developers.recurly.com/api/v2021-02-25/#operation/list_account_subscriptions }
-    # @param params [Hash] Optional query string parameters:
-    #        :ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
-    #                      commas as separators, e.g. +ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6+.
-    #        :limit [Integer] Limit number of records 1-200.
-    #        :order [String] Sort order.
-    #        :sort [String] Sort field. You *really* only want to sort by +updated_at+ in ascending
-    # ex:
-    # params = { limit: RECORDS_LIMIT, order: :asc, .....}
-    # ex: client.site_subscriptions(params)
-    def site_subscriptions(**params)
-      resp = request_api(path: 'subscriptions', params: params)
-      handle_response!(resp)
-    end
-
-    # Create subscription(new purchase) by ssor_id(Recurly Account code)
-    # { https://developers.recurly.com/api/v2021-02-25/index.html#operation/create_purchase }
-    # @param ssor_id [String] Required, user SSOR_ID (i.e. Reculry Account Code)
-    # @param plan_code [String] Required, plan_code or ID
-    # @param billing_token [String] Required, token genereted by recurlyjs while checkout
-    # @param gateway_code [String] Optional,
-    #   Payment gateway identifier to be used for the purchase transaction
-    #   ( required only if handling Braintree Multiple Merchant accounts )
-    # @param account_info [Hash] Optional query parameters(user provided info while checkout)
-    #      :first_name [String], user First Name
-    #      :last_name [String], user Last Name
-    #      :email [String] user Email
-    # TODO: fetch user email, first_name, last_name by ssor_id connecting to SsorClient
-    # Better to pass first_name, last_name, email fetched from Checkout Page,
-    #   instead of extra DB call to SSOR to get the user details
-    def create_subscription(ssor_id:, billing_token:, plan_code:,
-                            gateway_code: nil, account_info: {})
-      account = { code: ssor_id,
-                  billing_info: { token_id: billing_token } }
-      purchase_payload = { currency: 'USD',
-                           account: account.merge!(account_info),
-                           subscriptions: [{ plan_code: plan_code }] }
-      purchase_payload[:gateway_code] = gateway_code if gateway_code
-      path = 'purchases'
-      resp = request_api(path: path, http_method: :post,
-                         payload: purchase_payload)
-      handle_response!(resp, payload_name: :purchase_info, single_node: true)
-    end
-
-    # Cancel a subscription by its id or UUID
-    # @param sub_id_or_uuid [String] Required
-    #    Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2.
-    #    For UUID use prefix uuid-, e.g. uuid-123457890
-    def cancel_subscription(sub_id_or_uuid)
-      path = "subscriptions/#{sub_id_or_uuid}/cancel"
-      resp = request_api(path: path, http_method: :put)
-      handle_response!(resp, payload_name: :subscription_info, single_node: true)
-    end
-  end
-end
+# frozen_string_literal: true
+
+module RecurlyApi
+  # API requests to fetch Subscriptions related data
+  class Client
+    # Fetch Account Subscriptions ---
+    # { https://developers.recurly.com/api/v2021-02-25/index.html#operation/list_account_subscriptions }
+    # @param ssor_id [String] Account ID(SsorID) or code.
+    # For ID no prefix is used e.g. +e28zov4fw0v2+. For code use prefix +code-+, e.g. +code-gold+.
+    # For SsorID no prefix is required
+    #  for other params ref documentation
+    def account_subscriptions(ssor_id:, recurly_query_params: {}, **optional_params)
+      path = "accounts/#{ssor_id}/subscriptions"
+      request_api(path_name: path, query_params: recurly_query_params, **optional_params) # cache_key_name: cache_key_name
+    end
+
+    # Checking if user already has subscription OR
+    # Checking if user has a subscription for particular plan by its code
+    # ---------------
+    # @param ssor_id [String] required, Recurly Account Code(i.e SsorID)
+    # @param plan_code [String] optional,
+    #    - if present then checks if user has subscription for that particular plan by its code
+    # Usage ex:
+    # client.check_user_subscription(ssor_id: '4900-0272-6875', plan_code: '000150d03d')
+    # response => { :success=>true, :status=>200, :has_subscription=>true }
+    def check_user_subscription(ssor_id:, plan_code: nil)
+      resp = account_subscriptions(ssor_id: "code-#{ssor_id}")
+      if resp[:success]
+        has_subscription = false
+        subs = resp[:data]
+        has_subscription = true if subs.any?
+        if plan_code
+          sub =  subs.detect { |s| s['plan']['code'].eql?(plan_code) }
+          has_subscription = sub ? true : false
+        end
+        { success: true, status: 200, has_subscription: has_subscription }
+      else
+        resp
+      end
+    end
+
+    # List a site's subscriptions
+    # { https://developers.recurly.com/api/v2021-02-25/#operation/list_account_subscriptions }
+    # @param recurly_query_params [Hash] Optional, Recurly query string parameters:
+    #      i. :ids [String] Filter results by their IDs. Up to 200 IDs can be passed at once using
+    #           commas as separators, e.g. <ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6>.
+    #     ii. :limit [Integer] Limit number of records 1-200.
+    #    iii. :order [String] Sort order.
+    #     iv: :sort [String] Sort field. You *really* only want to sort by <updated_at> in ascending
+    # ex:
+    # recurly_query_params = { limit: RECORDS_LIMIT, order: :asc, .....}
+    # ex: client.site_subscriptions(params)
+    def site_subscriptions(recurly_query_params: {}, **optional_params)
+      request_api(path_name: 'subscriptions', query_params: recurly_query_params, **optional_params)
+    end
+
+    # Create subscription(new purchase) by ssor_id(Recurly Account code)
+    # { https://developers.recurly.com/api/v2021-02-25/index.html#operation/create_purchase }
+    # @param ssor_id [String] Required, user SSOR_ID (i.e. Reculry Account Code)
+    # @param plan_code [String] Required, plan_code or ID
+    # @param billing_token [String] Required, token genereted by recurlyjs while checkout
+    # @param gateway_code [String] Optional,
+    #   Payment gateway identifier to be used for the purchase transaction
+    #   ( required only if handling Braintree Multiple Merchant accounts )
+    # @param account_info [Hash] Optional query parameters(user provided info while checkout)
+    #      :first_name [String], user First Name
+    #      :last_name [String], user Last Name
+    #      :email [String] user Email
+    # TODO: fetch user email, first_name, last_name by ssor_id connecting to SsorClient
+    # Better to pass first_name, last_name, email fetched from Checkout Page,
+    #   instead of extra DB call to SSOR to get the user details
+    def create_subscription(ssor_id:, billing_token:, plan_code:,
+                            gateway_code: nil, account_info: {})
+      account = { code: ssor_id,
+                  billing_info: { token_id: billing_token } }
+      purchase_payload = { currency: 'USD',
+                           account: account.merge!(account_info),
+                           subscriptions: [{ plan_code: plan_code }] }
+      purchase_payload[:gateway_code] = gateway_code if gateway_code
+      path = 'purchases'
+      request_api(path_name: path, http_method: :post,
+                  payload: purchase_payload)
+    end
+
+    # Cancel a subscription by its id or UUID
+    # @param sub_id_or_uuid [String] Required
+    #    Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2.
+    #    For UUID use prefix uuid-, e.g. uuid-123457890
+    def cancel_subscription(sub_id_or_uuid)
+      path = "subscriptions/#{sub_id_or_uuid}/cancel"
+      request_api(path_name: path, http_method: :put)
+    end
+  end
+end

data/lib/recurly_api/exception_handler.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Common Exception Handler for all RestClient & Recurly API Server returned errors
+module RecurlyApi
+  #  Handles all possible exceptions that are returned by RestClient and Recurly Server and logs everything
+  module ExceptionHandler
+    def recurly_api_exception_handler(&block)
+      # block.call
+      yield
+    rescue RestClient::Unauthorized, RestClient::Forbidden => e
+      # https://www.rubydoc.info/gems/rest-client/1.6.7/frames#label-Result+handling
+      logger.error("#{logger_heading} ERROR: Access denied to Recurly API")
+      raise e.response
+    rescue RestClient::ImATeapot => e
+      logger.error("#{logger_heading} ERROR: Recurly Server is a teapot! # RFC 2324")
+      raise e.response
+    rescue RestClient::MovedPermanently,
+        RestClient::Found,
+        RestClient::TemporaryRedirect => e
+      logger.error("#{logger_heading} ERROR: Follow redirection- #{e.response.follow_redirection}")
+      raise e.response
+    rescue RestClient::ExceptionWithResponse => e
+      logger.error("#{logger_heading} ERROR: RestClient::ExceptionWithResponse")
+      raise e.response
+    rescue RestClient::Exception => e
+      logger.error("#{logger_heading} ERROR: RestClient::Exception")
+      raise e.response
+    # rescue StandardError => e # Note:  don't rescue standard error
+    #   logger.error("#{logger_heading} ERROR: Internal Server Error")
+    #   # e.backtrace.join("\n  ")
+    #   raise e.message
+    end
+  end
+end

data/lib/recurly_api/logging.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Logger for Gem
+module RecurlyApi
+  # fallback to STDOUT for non-rails project
+  module Logging
+    #  accessor setter method
+    attr_writer :logger
+
+    # Fallback to STDOUT logger for non-rails applications
+    # Usage examples to logging details in RecurlyApi:Client
+    # a. logger.info("I'm an info log")
+    # b. logger.warn("I'm a warn log")
+    # c. logger.error("I'm an error log: error message")
+    # d. logger.fatal("I'm a fatal log")
+    def logger
+      @logger ||= defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+    end
+
+    # Classical set method(instead used attr_writer)
+    # def logger=(logger)
+    #   @logger = logger
+    # end
+
+    def logger_heading
+      'tribune_recurly_api'
+    end
+
+    def logger_cache_heading
+      "#{logger_heading} CACHING"
+    end
+  end
+end

data/lib/recurly_api/rate_limiting.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Recurly rate limiting
+# { https://developers.recurly.com/api/v2019-10-10/#section/Getting-Started/Limits }
+# The rate limit is calculated over a sliding 5 minute window.
+# This means a production site could make 4,000 requests within one minute and not hit the rate limit
+# so long as the site made less than 1,000 requests during the prior 4 minute
+#  --------------
+# Response Headers that returned related to rate limiting by Recurly.
+# x_ratelimit_limit: The maximum number of requests available in the current time frame(5-minite window)
+# x_ratelimit_remaining: the number of requests left for the 5-minute window
+# x_ratelimit_reset: the remaining window before the rate limit resets, in UNIX Epoch seconds
+module RecurlyApi
+  # Retry again in case rate limit exceeded
+  module RateLimiting
+    attr_accessor :ratelimit_retries
+    RATE_LIMIT_MAX_RETRIES = 3
+
+    # Check if rate limit exceeded or not using resp status code OR x_ratelimit_remaining header
+    def rate_limit_exceeded?
+      ratelimit_remaining = recurly_response.headers[:x_ratelimit_remaining]
+      logger.info("x_ratelimit_remaining---- : #{ratelimit_remaining}")
+      recurly_response.code.eql?(429) || (ratelimit_remaining && ratelimit_remaining.to_i < 1) # 1998
+    end
+
+    def retry_on_rate_limit_exceed
+      max_retries = ratelimit_retries # max count to retry if rate limit requests are exceeded.
+      retry_count = 0
+      delay = 1 # in seconds
+      begin
+        raise 'API Rate limit exceeded' if rate_limit_exceeded?
+      rescue StandardError => _e
+        logger.warn "API Rate limit exceeded retrying again. Retries left: #{max_retries - retry_count}"
+        sleep delay += retry_count
+        retry_count += 1
+        retry if retry_count < max_retries
+      end
+    end
+
+    def rate_limit_exceed_response
+      resp_headers = recurly_response.headers
+      rate_limit_info = { limit: resp_headers[:x_ratelimit_limit],
+                          remaining: resp_headers[:x_ratelimit_remaining],
+                          reset_time_seconds: resp_headers[:x_ratelimit_reset],
+                          reset_time: DateTime.strptime(resp_headers[:x_ratelimit_reset], '%s') }
+      { success: false, status_code: 429,
+        error: 'Recurly API Rate limit exceeded',
+        message: 'Too Many Requests, See rate-limiting for more info',
+        rate_limit_info: rate_limit_info }
+    end
+  end
+end

data/lib/recurly_api/version.rb

@@ -1,6 +1,18 @@
-# frozen_string_literal: true
-
-# Gem visioning
-module RecurlyApi
-  VERSION = '0.4.3'
-end
+# frozen_string_literal: true
+
+# Gem visioning
+# fallow below ref doc to release new version of Gem
+#   -https://guides.rubygems.org/patterns/
+module RecurlyApi
+  # MAJOR = 1
+  # MINOR = 0
+  # TINY = 4
+  # PRE = nil
+  #
+  # STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.').freeze
+  #
+  # def self.to_s
+  #   STRING
+  # end
+  VERSION = '1.0.0'
+end

metadata

@@ -1,57 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: tribune_recurly_api
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 1.0.0
 platform: ruby
 authors:
 - udevulapally
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-06-02 00:00:00.000000000 Z
+date: 2021-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: rest-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
-  type: :development
+        version: 1.8.0
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 1.8.0
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '10.0'
 - !ruby/object:Gem::Dependency
-  name: rest-client
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.8.0
-  type: :runtime
+        version: '3.0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.8.0
+        version: '3.0'
 description: Wrapper for connecting to Recurly V3 API.
 email:
 - udevulapally@tribpub.com
@@ -60,17 +74,22 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/recurly_api.rb
+- lib/recurly_api/caching.rb
 - lib/recurly_api/client.rb
 - lib/recurly_api/client/accounts.rb
 - lib/recurly_api/client/other_requests.rb
 - lib/recurly_api/client/plans.rb
 - lib/recurly_api/client/subscriptions.rb
+- lib/recurly_api/exception_handler.rb
+- lib/recurly_api/logging.rb
+- lib/recurly_api/rate_limiting.rb
 - lib/recurly_api/version.rb
 - lib/tribune_recurly_api.rb
 homepage:
 licenses: []
 metadata:
   allowed_push_host: https://rubygems.org/
+  homepage_uri: https://diggit.int.tribops.com/gems/tribune_recurly_api/
 post_install_message:
 rdoc_options: []
 require_paths: