iron_bank 0.1.0 → 0.7.1

data/iron_bank.gemspec

@@ -1,15 +1,23 @@
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'iron_bank/version'
 
 Gem::Specification.new do |spec|
   spec.name     = 'iron_bank'
   spec.version  = IronBank::VERSION
-  spec.authors  = ['Mickael Pham']
-  spec.email    = ['mickael.pham@gmail.com']
-  spec.summary  = 'The Iron Bank is always glad to be of service.'
-  spec.homepage = 'https://github.com/mickaelpham/iron_bank'
-  spec.license  = 'Nonstandard'
+  spec.summary  = 'An opinionated Ruby interface to the Zuora API.'
+  spec.homepage = 'https://github.com/zendesk/iron_bank'
+  spec.license  = 'Apache-2.0'
+  spec.authors  = ['Mickael Pham', 'Cheng Cui', 'Ryan Ringler', 'Mustafa Turan']
+
+  spec.email = [
+    'mickael@zendesk.com',
+    'ccui@zendesk.com',
+    'rringler@zendesk.com',
+    'mturan@zendesk.com'
+  ]
 
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
@@ -19,8 +27,24 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.15'
-  spec.add_development_dependency 'rake',    '~> 10.0'
-  spec.add_development_dependency 'rspec',   '~> 3.0'
-  spec.add_development_dependency 'pry',     '~> 0.10'
+  spec.add_development_dependency 'bump',             '~> 0.5'
+  spec.add_development_dependency 'bundler',          '~> 1.15'
+  spec.add_development_dependency 'dotenv',           '~> 2.2'
+  spec.add_development_dependency 'factory_bot',      '~> 4.10'
+  spec.add_development_dependency 'private_gem',      '~> 1.1'
+  spec.add_development_dependency 'pry-byebug',       '~> 3.4'
+  spec.add_development_dependency 'rake',             '~> 12.0'
+  spec.add_development_dependency 'reek',             '~> 4.6'
+  spec.add_development_dependency 'rspec',            '~> 3.0'
+  spec.add_development_dependency 'rubocop',          '~> 0.52'
+  spec.add_development_dependency 'shoulda-matchers', '~> 3.1'
+  spec.add_development_dependency 'simplecov',        '~> 0.15'
+  spec.add_development_dependency 'timecop',          '~> 0.9.0'
+  spec.add_development_dependency 'vcr',              '~> 4.0'
+  spec.add_development_dependency 'webmock',          '~> 3.0'
+
+  spec.add_dependency 'ddtrace',            '~> 0'
+  spec.add_dependency 'faraday',            '~> 0'
+  spec.add_dependency 'faraday_middleware', '~> 0'
+  spec.add_dependency 'nokogiri',           '~> 1'
 end

data/lib/generators/iron_bank/install/install_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module IronBank
+  module Generators
+    # Allow us to run `rails generate iron_bank:install`
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def create_iron_bank_initializer
+        copy_file 'iron_bank.rb', 'config/initializers/iron_bank.rb'
+      end
+
+      def display_readme_in_terminal
+        readme 'README'
+      end
+    end
+  end
+end

data/lib/generators/iron_bank/install/templates/README

@@ -0,0 +1,16 @@
+*******************************************************************************
+
+Next steps:
+
+1. Edit the config/initializers/iron_bank.rb file with your Zuora credentials
+
+2. Export the schema for your Zuora tenant by running in the Rails console:
+
+    IronBank::Schema.export
+
+3. (optional) Export your product catalog by running in the Rails console:
+
+    IronBank::LocalRecords.export
+    exit # need to exit the session to finish exporting the local records
+
+*******************************************************************************

data/lib/generators/iron_bank/install/templates/iron_bank.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+IronBank.configure do |config|
+  # Zuora OAuth client ID
+  config.client_id = '<my-client-id-from-zuora>'
+
+  # Zuora OAuth client secret
+  config.client_secret = '<my-secret-from-zuora>'
+
+  # Zuora API domain (apisandbox, production, etc.)
+  config.domain = 'rest.apisandbox.zuora.com'
+
+  # Directory where the metadata XML files (Zuora schema) will be stored
+  config.schema_directory = 'config/zuora/schema'
+
+  # Directory where the local export CSV files will be stored
+  config.export_directory = 'config/zuora/local_records'
+
+  # Zuora authentication type:
+  #   - `token` uses OAuth and is the *recommended* approach
+  #   - `cookie` uses username/password for Zuora environments that do not
+  #              support OAuth authentication, e.g., services environment. If
+  #              using `cookie` authentication, then use an API user username as
+  #              the `client_id` and the API user password as `client_secret`
+  config.auth_type = 'token'
+
+  # Set the gem to use the Rails logger
+  config.logger = Rails.logger
+end

data/lib/iron_bank/action.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module IronBank
+  # Base class for Zuora actions, e.g., subscribe
+  #
+  class Action
+    private_class_method :new
+
+    def self.call(args)
+      new(args).call
+    end
+
+    def call
+      IronBank.client.connection.post(endpoint, params).body
+    end
+
+    private
+
+    attr_reader :args
+
+    def initialize(args)
+      @args = args
+    end
+
+    def endpoint
+      "v1/action/#{name.downcase}"
+    end
+
+    def name
+      self.class.name.split('::').last
+    end
+
+    def requests(type: :upper)
+      args.fetch(:objects).map do |object|
+        IronBank::Object.new(object).deep_camelize(type: type)
+      end
+    end
+  end
+end

data/lib/iron_bank/actions/amend.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Actions
+    # Use the amend call to change a subscription
+    # https://www.zuora.com/developer/api-reference/#operation/Action_POSTamend
+    #
+    class Amend < Action
+      private
+
+      def params
+        { requests: args }
+      end
+    end
+  end
+end

data/lib/iron_bank/actions/create.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Actions
+    # Create one or more objects of a specific type
+    # https://www.zuora.com/developer/api-reference/#operation/Action_POSTcreate
+    #
+    class Create < Action
+      private
+
+      def params
+        {
+          objects: requests,
+          type:    args.fetch(:type)
+        }
+      end
+    end
+  end
+end

data/lib/iron_bank/actions/delete.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Actions
+    # Delete one or more objects of the same type
+    # https://www.zuora.com/developer/api-reference/#operation/Action_POSTdelete
+    #
+    class Delete < Action
+      private
+
+      def params
+        {
+          ids:  args.fetch(:ids),
+          type: args.fetch(:type)
+        }
+      end
+    end
+  end
+end

data/lib/iron_bank/actions/execute.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Actions
+    # Use the execute call to execute the process to split an invoice into
+    # multiple invoices (the original invoice must be in draft status)
+    # https://www.zuora.com/developer/api-reference/#operation/Action_POSTexecute
+    #
+    class Execute < Action
+      private
+
+      def params
+        {
+          ids:         args.fetch(:ids),
+          synchronous: args.fetch(:synchronous),
+          type:        args.fetch(:type)
+        }
+      end
+    end
+  end
+end

data/lib/iron_bank/actions/generate.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Actions
+    # Generate an on-demand invoice for a specific customer
+    # https://www.zuora.com/developer/api-reference/#operation/Action_POSTgenerate
+    #
+    class Generate < Action
+      private
+
+      def params
+        {
+          objects: args.fetch(:objects).map(&:deep_camelize),
+          type:    args.fetch(:type)
+        }
+      end
+    end
+  end
+end

data/lib/iron_bank/actions/query.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Actions
+    # Query Zuora using ZOQL
+    # https://knowledgecenter.zuora.com/DC_Developers/K_Zuora_Object_Query_Language
+    #
+    class Query < Action
+      private
+
+      def params
+        { 'queryString' => args }
+      end
+    end
+  end
+end

data/lib/iron_bank/actions/query_more.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Actions
+    # Query More call to Zuora REST API
+    # https://www.zuora.com/developer/api-reference/#operation/Action_POSTqueryMore
+    #
+    class QueryMore < Action
+      private
+
+      def params
+        { 'queryLocator' => args }
+      end
+
+      # NOTE: Zuora API endpoint is case-sensitive.
+      def endpoint
+        'v1/action/queryMore'
+      end
+    end
+  end
+end

data/lib/iron_bank/actions/subscribe.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Actions
+    # Use the subscribe call to bundle information required to create at least
+    # one new subscription
+    # https://www.zuora.com/developer/api-reference/#operation/Action_POSTsubscribe
+    #
+    class Subscribe < Action
+      def call
+        body = IronBank.client.connection.post(endpoint, params).body
+
+        if body.is_a?(Array)
+          body.map { |result| IronBank::Object.new(result).deep_underscore }
+        else
+          IronBank::Object.new(body).deep_underscore
+        end
+      end
+
+      private
+
+      def params
+        { subscribes: subscribe_requests }
+      end
+
+      def subscribe_requests
+        requests = [args].flatten
+        requests.map { |request| IronBank::Object.new(request).deep_camelize }
+      end
+    end
+  end
+end

data/lib/iron_bank/actions/update.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Actions
+    # Update the information in one or more objects of the same type
+    # https://www.zuora.com/developer/api-reference/#operation/Action_POSTupdate
+    #
+    class Update < Action
+      private
+
+      def params
+        {
+          objects: requests,
+          type:    args.fetch(:type)
+        }
+      end
+    end
+  end
+end

data/lib/iron_bank/associations.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module IronBank
+  # Define association methods for Zuora resources.
+  #
+  module Associations
+    # Define class methods
+    #
+    module ClassMethods
+      def with_one(name, options = {})
+        resource_name = options.fetch(
+          :resource_name,
+          IronBank::Utils.camelize(name)
+        )
+        foreign_key = options.fetch(:foreign_key, name.to_s + '_id')
+
+        define_method(name) do
+          return unless (foreign_key_value = public_send(foreign_key))
+
+          with_memoization(name) do
+            # NOTE: we retrieve the constant here to prevent the need to order
+            # our `require <file>` statements in `iron_bank.rb`
+            klass = IronBank::Resources.const_get(resource_name)
+            klass.find(foreign_key_value)
+          end
+        end
+
+        # Association is "also known as"
+        aka = options[:aka]
+        alias_method aka, name if aka
+      end
+
+      def with_many(name, options = {})
+        resource_name = options.fetch(
+          :resource_name,
+          IronBank::Utils.camelize(name.to_s.chop)
+        )
+
+        foreign_key = options.fetch(
+          :foreign_key,
+          IronBank::Utils.underscore(object_name) + '_id'
+        )
+
+        define_method(name) do
+          with_memoization(name) do
+            # NOTE: we retrieve the constant here to prevent the need to order
+            # our `require <file>` statements in `iron_bank.rb`
+            klass      = IronBank::Resources.const_get(resource_name)
+            conditions = options.fetch(:conditions, {}).
+                         merge("#{foreign_key}": id)
+            items      = klass.where(conditions)
+            IronBank::Collection.new(klass, conditions, items)
+          end
+        end
+
+        # Association is "also known as"
+        aka = options[:aka]
+        alias_method aka, name if aka
+      end
+    end
+
+    def with_memoization(name)
+      # NOTE: We use `instance_variables.include?` instead of `defined?`.
+      # Later it will always evaluate to `true` because it's an expression.
+      if instance_variables.include?(:"@#{name}")
+        return instance_variable_get(:"@#{name}")
+      end
+
+      memoizable = yield
+      instance_variable_set(:"@#{name}", memoizable)
+    end
+  end
+end

data/lib/iron_bank/authentication.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module IronBank
+  # Get a valid token or session HTTP request header for IronBank
+  #
+  class Authentication
+    extend Forwardable
+
+    attr_reader :session
+
+    def_delegators :session, :header, :expired?
+
+    def initialize(params)
+      @auth_type = params.delete(:auth_type)
+      @params    = params
+      create_session
+    end
+
+    def create_session
+      @session = adapter.new(params)
+    end
+    alias renew_session create_session
+
+    private
+
+    attr_reader :auth_type, :params
+
+    def adapter
+      @adapter ||=
+        if auth_type == 'cookie'
+          IronBank::Authentications::Cookie
+        else
+          IronBank::Authentications::Token
+        end
+    end
+  end
+end

data/lib/iron_bank/authentications/cookie.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Authentications
+    # Get a cookie to enable authenticated calls to Zuora through Session.
+    #
+    class Cookie
+      include IronBank::OpenTracing
+
+      TEN_MINUTES = 600
+      ONE_HOUR    = 3600
+
+      def initialize(client_id:, client_secret:, base_url:)
+        @client_id     = client_id
+        @client_secret = client_secret
+        @base_url      = base_url
+        fetch_cookie
+      end
+
+      def expired?
+        # Ten minutes as a margin of error in order to renew token in time
+        expires_at < Time.now + TEN_MINUTES
+      end
+
+      def header
+        { 'Cookie' => use }
+      end
+
+      private
+
+      attr_reader :client_id, :client_secret, :base_url, :cookie, :zsession,
+                  :expires_at
+
+      def use
+        refetch_cookie if expired?
+        zsession
+      end
+
+      def fetch_cookie
+        response    = authenticate
+        @cookie     = response.headers['set-cookie']
+        @zsession   = fetch_zsession
+        @expires_at = Time.now + ONE_HOUR
+      end
+      alias refetch_cookie fetch_cookie
+
+      def fetch_zsession
+        /ZSession=([^\;]+)/.match(cookie)[0]
+      end
+
+      def authenticate
+        connection.post('v1/connections', {})
+      end
+
+      def connection
+        @connection ||= Faraday.new(faraday_config) do |conn|
+          conn.use      :ddtrace, open_tracing_options if open_tracing_enabled?
+          conn.request  :url_encoded
+          conn.response :logger, IronBank.logger
+          conn.response :json
+          conn.adapter  Faraday.default_adapter
+        end
+      end
+
+      def faraday_config
+        {
+          url:     base_url,
+          headers: authentication_headers
+        }
+      end
+
+      def authentication_headers
+        {
+          apiaccesskeyid:     client_id,
+          apisecretaccesskey: client_secret
+        }
+      end
+    end
+  end
+end

data/lib/iron_bank/authentications/token.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Authentications
+    # Get a bearer token to enable authenticated calls to Zuora through OAuth.
+    #
+    class Token
+      include IronBank::OpenTracing
+
+      # Generic token error.
+      #
+      class Error < StandardError; end
+
+      # Thrown when the access_token is not valid.
+      #
+      class InvalidAccessToken < Error; end
+
+      TEN_MINUTES = 600
+      ONE_HOUR    = 3600
+
+      def initialize(client_id:, client_secret:, base_url:)
+        @client_id     = client_id
+        @client_secret = client_secret
+        @base_url      = base_url
+        fetch_token
+      end
+
+      def expired?
+        # Ten minutes as a margin of error in order to renew token in time
+        expires_at < Time.now + TEN_MINUTES
+      end
+
+      def header
+        { 'Authorization' => "Bearer #{use}" }
+      end
+
+      private
+
+      attr_reader :client_id, :client_secret, :base_url, :access_token,
+                  :expires_at
+
+      def use
+        refetch_token if expired?
+        access_token
+      end
+
+      def fetch_token
+        response      = authenticate || {}
+        @access_token = response.fetch('access_token', nil)
+        @expires_at   = Time.now + response.fetch('expires_in', ONE_HOUR).to_i
+        validate_access_token
+      end
+      alias refetch_token fetch_token
+
+      def authenticate
+        connection.post('/oauth/token', authentication_params).body
+      end
+
+      def connection
+        @connection ||= Faraday.new(url: base_url) do |conn|
+          conn.use      :ddtrace, open_tracing_options if open_tracing_enabled?
+          conn.request  :url_encoded
+          conn.response :logger, IronBank.logger
+          conn.response :json
+          conn.adapter  Faraday.default_adapter
+        end
+      end
+
+      def authentication_params
+        {
+          client_id:     client_id,
+          client_secret: client_secret,
+          grant_type:    'client_credentials'
+        }
+      end
+
+      def validate_access_token
+        raise InvalidAccessToken, access_token unless access_token
+      end
+    end
+  end
+end

data/lib/iron_bank/cacheable.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module IronBank
+  # Use the provided cache if present.
+  #
+  module Cacheable
+    def reload
+      remove_instance_vars
+      @remote = self.class.find(id, force: true).remote
+    end
+
+    private
+
+    def remove_instance_vars
+      # Substract predefined variables from the instance variables
+      (instance_variables - [:@remote]).each do |var|
+        remove_instance_variable(:"#{var}")
+      end
+    end
+
+    def cache
+      self.class.cache
+    end
+
+    # Override queryable class methods to use cache if present.
+    #
+    module ClassMethods
+      def find(id, force: false)
+        return super(id) unless cache
+
+        cache.fetch(id, force: force) { super(id) }
+      end
+
+      def where(conditions)
+        # Conditions can be empty when called from #all, it does not make sense
+        # to try to cache all records returned then.
+        return super if conditions.empty?
+
+        return super unless cache
+
+        # Ensure we are not colliding when the conditions are similar for two
+        # different resources, like Account and Subscription.
+        cache_key = conditions.merge(object_name: name)
+        cache.fetch(cache_key) { super }
+      end
+
+      def cache
+        IronBank.configuration.cache
+      end
+    end
+  end
+end