iron_bank 0.1.0 → 0.7.1

data/lib/iron_bank/logger.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require 'logger'
+
+module IronBank
+  # Default logger for IronBank events
+  #
+  class Logger
+    extend Forwardable
+
+    PROGNAME = 'iron_bank'
+    LEVEL    = ::Logger::DEBUG
+
+    def_delegators :@logger, :debug, :info, :warn, :error, :fatal
+
+    def initialize(logger: ::Logger.new(STDOUT), level: LEVEL)
+      @logger          = logger
+      @logger.progname = PROGNAME
+      @logger.level    = level
+    end
+  end
+end

data/lib/iron_bank/metadata.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module IronBank
+  # Metadata to provide accessors to Zuora resources.
+  #
+  module Metadata
+    # Can be overriden to exclude specific fields for a given resource, see
+    # `Account` class for an example
+    def exclude_fields
+      []
+    end
+
+    def fields
+      return [] unless schema
+
+      @fields ||= schema.fields.map(&:name) - exclude_fields
+    end
+
+    def query_fields
+      return [] unless schema
+
+      @query_fields ||= schema.query_fields - exclude_fields
+    end
+
+    def schema
+      @schema ||= IronBank::Schema.for(object_name)
+    end
+
+    def with_schema
+      fields.each do |field|
+        method_name = IronBank::Utils.underscore(field)
+        define_method(:"#{method_name}") { remote[field] }
+      end
+    end
+  end
+end

data/lib/iron_bank/object.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module IronBank
+  # This object holds the initial payload (hash) sent through one of the
+  # action/operation. It exposes methods to convert the payload to either
+  # upper camel case (typically used by actions) or lower camel case.
+  #
+  # It is also use to parse the response from Zuora and convert it into a Ruby-
+  # friendly Hash.
+  #
+  class Object
+    SNOWFLAKE_FIELDS = ['fieldsToNull'].freeze
+
+    attr_reader :payload
+
+    def initialize(payload)
+      @payload = payload
+    end
+
+    # FIXME: refactor both camelize/underscore methods into one
+    def deep_camelize(type: :upper)
+      payload.each_pair.with_object({}) do |(field, value), hash|
+        field = field.to_s
+
+        key = if SNOWFLAKE_FIELDS.include?(field)
+                field
+              else
+                IronBank::Utils.camelize(field, type: type)
+              end
+
+        hash[key] = camelize(value, type: type)
+      end
+    end
+
+    # FIXME: refactor both camelize/underscore methods into one
+    def deep_underscore
+      payload.each_pair.with_object({}) do |(field, value), hash|
+        key       = IronBank::Utils.underscore(field.to_s).to_sym
+        hash[key] = underscore(value)
+      end
+    end
+
+    private
+
+    # FIXME: refactor both camelize/underscore methods into one
+    def camelize(value, type: :upper)
+      if value.is_a?(Array)
+        camelize_array(value, type: type)
+      elsif value.is_a?(Hash)
+        IronBank::Object.new(value).deep_camelize(type: type)
+      elsif value.is_a?(IronBank::Object)
+        value.deep_camelize(type: type)
+      else
+        value
+      end
+    end
+
+    # FIXME: refactor both camelize/underscore methods into one
+    def camelize_array(value, type: :upper)
+      value.each.with_object([]) do |item, payload|
+        item = IronBank::Object.new(item) if item.is_a?(Hash)
+        item = item.deep_camelize(type: type) unless item.is_a?(String)
+
+        payload.push(item)
+      end
+    end
+
+    # FIXME: refactor both camelize/underscore methods into one
+    def underscore(value)
+      if value.is_a?(Array)
+        underscore_array(value)
+      elsif value.is_a?(Hash)
+        IronBank::Object.new(value).deep_underscore
+      elsif value.is_a?(IronBank::Object)
+        value.deep_underscore
+      else
+        value
+      end
+    end
+
+    # FIXME: refactor both camelize/underscore methods into one
+    def underscore_array(value)
+      value.each.with_object([]) do |item, payload|
+        item = IronBank::Object.new(item) if item.is_a?(Hash)
+        payload.push(item.deep_underscore)
+      end
+    end
+  end
+end

data/lib/iron_bank/open_tracing.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module IronBank
+  # Open Tracing helper module
+  module OpenTracing
+    def open_tracing_enabled?
+      IronBank.configuration.open_tracing_enabled
+    end
+
+    def open_tracing_options
+      {
+        distributed_tracing: true,
+        split_by_domain:     false
+      }
+    end
+  end
+end

data/lib/iron_bank/operation.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module IronBank
+  # Base class for Zuora operations, e.g., billing preview
+  #
+  class Operation
+    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/operations/#{IronBank::Utils.kebab(name)}"
+    end
+
+    def name
+      self.class.name.split('::').last
+    end
+  end
+end

data/lib/iron_bank/operations/billing_preview.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Operations
+    # Delete one or more objects of the same type
+    # https://www.zuora.com/developer/api-reference/#operation/Action_POSTdelete
+    #
+    class BillingPreview < Operation
+      private
+
+      def params
+        IronBank::Object.new(args).deep_camelize(type: :lower)
+      end
+    end
+  end
+end

data/lib/iron_bank/query_builder.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module IronBank
+  # A query builder helps buidling a syntaxically correct query using ZOQL.
+  #
+  class QueryBuilder
+    private_class_method :new
+
+    def self.zoql(object, fields, conditions = {})
+      new(object, fields, conditions).zoql
+    end
+
+    def zoql
+      query = "select #{query_fields} from #{object}"
+      conditions.empty? ? query : "#{query} where #{query_conditions}"
+    end
+
+    private
+
+    attr_reader :object, :fields, :conditions
+
+    def initialize(object, fields, conditions)
+      @object     = object
+      @fields     = fields
+      @conditions = conditions
+    end
+
+    def query_fields
+      fields.join(',')
+    end
+
+    def query_conditions
+      ensure_range_single_condition
+
+      case conditions
+      when Hash
+        hash_query_conditions
+      end
+    end
+
+    def range_query_builder(field, value)
+      value.each.with_object([]) do |option, range_query|
+        range_query << "#{field}='#{option}'"
+      end.join(' OR ')
+    end
+
+    def hash_query_conditions
+      conditions.each.with_object([]) do |(field, value), filters|
+        # TODO: sanitize the value
+        field = IronBank::Utils.camelize(field)
+        filters << current_filter(field, value)
+      end.join(' AND ')
+    end
+
+    def current_filter(field, value)
+      if value.is_a?(Array)
+        range_query_builder(field, value)
+      elsif [true, false].include? value
+        "#{field}=#{value}"
+      else
+        "#{field}='#{value}'"
+      end
+    end
+
+    def ensure_range_single_condition
+      return if conditions.count <= 1
+      return unless conditions.values.any? { |value| value.is_a?(Array) }
+
+      raise 'Filter ranges must be used in isolation.'
+    end
+  end
+end

data/lib/iron_bank/queryable.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module IronBank
+  # Query-like features, such as `find` and `where` methods for a resource.
+  #
+  module Queryable
+    # We use the REST endpoint for the `find` method
+    def find(id)
+      raise IronBank::NotFound unless id
+
+      new(
+        IronBank.client.connection.get("v1/object/#{object_name}/#{id}").body
+      )
+    end
+
+    # This methods leverages the fact that Zuora only returns 2,000 records at a
+    # time, hance providing a default batch size
+    def find_each
+      return enum_for(:find_each) unless block_given?
+
+      client       = IronBank.client
+      query_string = IronBank::QueryBuilder.zoql(object_name, query_fields)
+      query_result = client.query(query_string) # up to 2k records from Zuora
+
+      loop do
+        query_result['records'].each { |data| yield new(data) }
+        break if query_result['done']
+
+        query_result = client.query_more(query_result['queryLocator'])
+      end
+    end
+
+    def all
+      where({})
+    end
+
+    def where(conditions)
+      query_string = IronBank::QueryBuilder.zoql(
+        object_name,
+        query_fields,
+        conditions
+      )
+
+      # FIXME: need to use logger instance instead
+      # puts "query: #{query_string}"
+
+      records = IronBank::Query.call(query_string)['records']
+      return [] unless records
+
+      records.each.with_object([]) do |data, result|
+        result << new(data)
+      end
+    end
+  end
+end

data/lib/iron_bank/resource.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module IronBank
+  # An Iron Bank RESTful resource.
+  #
+  class Resource
+    include IronBank::Associations
+    extend IronBank::Associations::ClassMethods
+    extend IronBank::Metadata
+    extend IronBank::Queryable
+
+    def self.object_name
+      name.split('::').last
+    end
+
+    def self.with_local_records
+      extend IronBank::Local
+    end
+
+    def self.with_cache
+      include IronBank::Cacheable
+      extend IronBank::Cacheable::ClassMethods
+    end
+
+    attr_reader :remote
+
+    def initialize(remote = {})
+      @remote = remote
+    end
+
+    # Every Zuora object has an ID, so we can safely declare it for each
+    # resource
+    def id
+      remote['Id']
+    end
+
+    def inspect
+      # NOTE: In Ruby, the IDs of objects start from the second bit on the right
+      # but in "value space" (used by the original `inspect` implementation)
+      # they start from the third bit on the right. Hence the bitsfhit operation
+      # here.
+      # https://stackoverflow.com/questions/2818602/in-ruby-why-does-inspect-print-out-some-kind-of-object-id-which-is-different
+      ruby_id = "#{self.class.name}:0x#{(object_id << 1).to_s(16)} id=\"#{id}\""
+      respond_to?(:name) ? "#<#{ruby_id} name=\"#{name}\">" : "#<#{ruby_id}>"
+    end
+
+    # Two resources are equals if their remote (from Zuora) data are similar
+    def ==(other)
+      other.is_a?(IronBank::Resource) ? remote == other.remote : false
+    end
+
+    def reload
+      remove_instance_vars
+      @remote = self.class.find(id).remote
+    end
+
+    def to_csv_row
+      self.class.fields.each.with_object([]) do |field, row|
+        row << remote[field]
+      end
+    end
+
+    def remove_instance_vars
+      # Substract predefined variables from the instance variables
+      (instance_variables - [:@remote]).each do |var|
+        remove_instance_variable(:"#{var}")
+      end
+    end
+  end
+end

data/lib/iron_bank/resources/account.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Resources
+    # A Zuora account is used for billing purposes: it holds many subscriptions,
+    # has many contacts (but only one bill to and one sold to contact), can have
+    # a default payment method, hence auto-pay can be activated for this account
+    # or not, is billed invoices and can pay them using an electronic payment
+    # method (usually a credit card, but PayPal is also accepted by Zuora).
+    #
+    class Account < Resource
+      # Tenants without credit memo activated cannot query these fields BUT they
+      # are still described as `selectable` through the metadata.
+      #
+      # Similarly, accounts with `TaxExemptStatus` set to `No` cannot query
+      # the `TaxExemptEntityUseCode` related fields.
+      def self.exclude_fields
+        %w[
+          TaxExemptEntityUseCode
+          TotalDebitMemoBalance
+          UnappliedCreditMemoAmount
+        ]
+      end
+      with_schema
+
+      # Contacts
+      with_one :bill_to, resource_name: 'Contact'
+      with_one :sold_to, resource_name: 'Contact'
+      with_many :contacts
+
+      # Subscriptions
+      with_many :subscriptions
+      with_many :active_subscriptions,
+                resource_name: 'Subscription',
+                conditions: { status: 'Active' }
+
+      # Invoices
+      with_many :invoices
+
+      # Payment Methods
+      with_one :default_payment_method, resource_name: 'PaymentMethod'
+      with_many :payment_methods
+
+      # Payments
+      with_many :payments
+
+      # Usages
+      with_many :usages
+
+      # Parent
+      with_one :parent, resource_name: 'Account'
+
+      def ultimate_parent
+        root if parent
+      end
+
+      def root
+        parent ? parent.root : self
+      end
+    end
+  end
+end

data/lib/iron_bank/resources/amendment.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Resources
+    # An amendment updates a subscription version and has a type: new product,
+    # update product, remove product, renewal, terms and conditions amendment.
+    #
+    class Amendment < Resource
+      with_schema
+      with_one :subscription
+    end
+  end
+end

data/lib/iron_bank/resources/catalog_tiers/discount_amount.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Resources
+    module CatalogTiers
+      # A tier that holds an discount ammount for a given product rate plan
+      # charge.
+      #
+      class DiscountAmount < ProductRatePlanChargeTier
+        def self.exclude_fields
+          %w[
+            Active
+            DiscountPercentage
+            IncludedUnits
+            OveragePrice
+            Price
+          ]
+        end
+
+        def self.object_name
+          superclass.object_name
+        end
+      end
+    end
+  end
+end

data/lib/iron_bank/resources/catalog_tiers/discount_percentage.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Resources
+    module CatalogTiers
+      # A tier that holds an discount percentage for a given product rate plan
+      # charge.
+      #
+      class DiscountPercentage < ProductRatePlanChargeTier
+        def self.exclude_fields
+          %w[
+            Active
+            DiscountAmount
+            IncludedUnits
+            OveragePrice
+            Price
+          ]
+        end
+
+        def self.object_name
+          superclass.object_name
+        end
+      end
+    end
+  end
+end

data/lib/iron_bank/resources/catalog_tiers/price.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Resources
+    module CatalogTiers
+      # A tier that holds an amount (cost) and a currency for a given product
+      # rate plan charge.
+      #
+      class Price < ProductRatePlanChargeTier
+        def self.exclude_fields
+          %w[
+            Active
+            DiscountAmount
+            DiscountPercentage
+            IncludedUnits
+            OveragePrice
+          ]
+        end
+
+        def self.object_name
+          superclass.object_name
+        end
+      end
+    end
+  end
+end

data/lib/iron_bank/resources/contact.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Resources
+    # A Zuora contact, belongs to an account, can be set as the sold to/bill to
+    # contact for a given account.
+    #
+    class Contact < Resource
+      with_schema
+      with_one :account
+    end
+  end
+end

data/lib/iron_bank/resources/export.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Resources
+    # Export ZOQL queries.
+    #
+    class Export < Resource
+      with_schema
+    end
+  end
+end

data/lib/iron_bank/resources/import.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Resources
+    # Import usages into Zuora.
+    #
+    class Import < Resource
+      with_schema
+      with_many :usages
+    end
+  end
+end

data/lib/iron_bank/resources/invoice.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Resources
+    # A Zuora invoice is generated through a bill run, belongs to an account and
+    # holds many invoice items.
+    #
+    class Invoice < Resource
+      # These fields are declared as `<selectable>true</selectable>` but Zuora
+      # returns a QueryError when trying to query an invoice with them. Also,
+      # the `Body` field can only be retrieved for a single invoice at a time.
+      def self.exclude_fields
+        %w[
+          AutoPay
+          BillRunId
+          BillToContactSnapshotId
+          Body
+          RegenerateInvoicePDF
+          SoldToContactSnapshotId
+        ]
+      end
+      with_schema
+
+      with_one :account
+
+      with_many :invoice_adjustments, aka: :adjustments
+      with_many :invoice_items, aka: :items
+      with_many :invoice_payments
+
+      # We can only retrieve one invoice body at a time, hence Body is excluded
+      # from the query fields, but is populated using the `find` class method
+      def body
+        remote['Body'] || reload['Body']
+      end
+    end
+  end
+end

data/lib/iron_bank/resources/invoice_adjustment.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Resources
+    # An invoice adjustment modifies the total invoice balance.
+    #
+    class InvoiceAdjustment < Resource
+      with_schema
+      with_one :account
+      with_one :invoice
+    end
+  end
+end

data/lib/iron_bank/resources/invoice_item.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module IronBank
+  module Resources
+    # An invoice item holds a charge that is billed to a customer.
+    #
+    class InvoiceItem < Resource
+      def self.exclude_fields
+        %w[
+          AppliedToChargeNumber
+          Balance
+        ]
+      end
+      with_schema
+
+      with_one :invoice
+      with_one :subscription
+
+      # NOTE: the `product_id` field is not always populated by Zuora in the GET
+      # request (`#find` method), I don't exactly know why.
+      with_one :product
+      with_one :charge
+    end
+  end
+end