ledger_sync 1.3.2 → 1.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05667fe1a37dc8edfcb33121d2eb5f08ad076b8b635ecaaf33809b663c830f68
-  data.tar.gz: 3b3a6c68af8ecf2ce04a8f789854fb1002b3d90d5e747e71d398aa1b1b8b4c9f
+  metadata.gz: 6c159bdb17d877ede52d532d64ca436bf590fd64d06f96f3302003bbade4a5e9
+  data.tar.gz: 4146c094eb32435710901c88442ebab06e51bfb8b32144604c159a02f5287e33
 SHA512:
-  metadata.gz: 14cdebe2e5342838d44202fbe9b11c28e09a6e18ccbb4827145d0b098833c1549c9e922bd8760555708358058df74ff5574a46b91aa67d48f347a99d2e5a0129
-  data.tar.gz: 8a48a4251273a4aa7a2cca65cc1eaed38c87d385caa2aeb1c3eaf63c76f0d67bf5af3099dcb16a1c4df82517e79c3bd35c8b41584a1a5197a584bce5c951ca5f
+  metadata.gz: 87e52ac4566ad46fd64a32a67e4ca2221b5c19638bd6fd0b2347a43b9934e4c6e2952a84efc83ee414e05c07e384b2e8e9f72a785066619b7c8a8a9780939f10
+  data.tar.gz: f887774835cbfaa38bfcf9a6a7d4b69760961875e86bb6096fdc36e8bdf19bdcdc11a24777e9277c818c734eaf85f1d3eadbd1ef90bcffd483c99ae681ae52a2

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ledger_sync (1.3.2)
+    ledger_sync (1.3.3)
       activemodel
       colorize
       coveralls
@@ -15,6 +15,7 @@ PATH
       netsuite
       nokogiri
       oauth2
+      pd_ruby
       resonad
       simply_serializable (>= 1.3.0)
       stripe
@@ -121,7 +122,7 @@ GEM
     nokogiri (1.10.7)
       mini_portile2 (~> 2.4.0)
     nori (2.6.0)
-    oauth2 (1.4.2)
+    oauth2 (1.4.3)
       faraday (>= 0.8, < 2.0)
       jwt (>= 1.0, < 3.0)
       multi_json (~> 1.3)
@@ -130,8 +131,10 @@ GEM
     parallel (1.17.0)
     parser (2.6.4.1)
       ast (~> 2.4.0)
+    pd_ruby (0.2.0)
+      colorize
     public_suffix (4.0.1)
-    rack (2.1.1)
+    rack (2.1.2)
     rainbow (3.0.0)
     rake (10.5.0)
     resonad (1.2.0)

data/README.md

@@ -79,14 +79,12 @@ end
 
 ## How it Works
 
-### The Library Structure
-
 This library consists of two important layers:
 
 1. Resources
 2. Adaptors
 
-#### Resources
+### Resources
 
 Resources are named ruby objects (e.g. `Customer`, `Payment`, etc.) with strict attributes (e.g. `name`, `amount`, etc.).  They are a layer between your application and an adaptor.  They can be validated using an adaptor.  You can create and use the resources, and an adaptor will update resources as needed based on the intention and outcome of that operation.
 
@@ -96,11 +94,59 @@ Resources have defined attributes.  Attributes are explicitly defined.  An error
 
 A subset of these `attributes` may be a `reference`, which is simply a special type of attribute that references another resource.  You can retrieve the references of a resource by calling `LedgerSync::Customer.references`.
 
+#### Custom Attributes
+
+Some ledgers (e.g. NetSuite) allow for custom attributes (or "fields"), which can vary by account and user.  To allow for custom attributes, you can create new resources, ledger serializers (see below), and validation contracts (see below).  Assuming your ledger supports the string attribute `foo` for customers, you could do the following:
+
+```ruby
+class CustomCustomer < LedgerSync::Customer
+  attribute :foo, type: LedgerSync::Type::String
+end
+```
+
+Depending on your use of LedgerSync, you may need to define resources dynamically with different custom attributes.  You could do so using something like the following:
+
+```ruby
+custom_attributes_for_customers = [
+  [
+    [:foo, LedgerSync::Type::String]
+  ],
+  [
+    [:foo, LedgerSync::Type::Integer],
+    [:bar, LedgerSync::Type::Boolean]
+  ]
+]
+
+custom_customer_classes = custom_attributes_for_customers.map do |attributes|
+  klass = Class.new(LedgerSync::Customer)
+  attributes.each do |name, type|
+    klass.attribute name, type: type
+  end
+  klass
+end
+
+klass1, klass2 = custom_customer_classes
+
+# First Custom Customer Class
+klass1.resource_attributes.include?(:foo) # => true
+klass1.resource_attributes[:foo].type # => #<LedgerSync::Type::String:0x00007fe04e9529b0 @precision=nil, @scale=nil, @limit=nil>
+klass1.resource_attributes.include?(:bar) # => false
+
+# Second Custom Customer Class
+klass2.resource_attributes.include?(:foo) # => true
+klass2.resource_attributes[:foo].type # => #<LedgerSync::Type::Integer:0x00007fe04e2c7898 @precision=nil, @scale=nil, @limit=nil, @range=-2147483648...2147483648>
+klass2.resource_attributes.include?(:bar) # => true
+klass2.resource_attributes[:bar].type # => #<LedgerSync::Type::Boolean:0x00007fe04e2e4f10 @precision=nil, @scale=nil, @limit=nil>
+```
+
+You can now use these custom resources in operations that require custom attributes.
+
 ### Adaptors
 
 Adaptors are ledger-specific ruby objects that contain all the logic to authenticate to a ledger, perform ledger-specific operations, and validate resources based on the requirements of the ledger.  Adaptors contain a number of useful objects:
 
 - adaptor
+- serializers
 - operations
 - searchers
 
@@ -108,6 +154,45 @@ Adaptors are ledger-specific ruby objects that contain all the logic to authenti
 
 The adaptor handles authentication and requests to the ledger.  Each adaptors initializer will vary based on the needs of that ledger.
 
+#### Serializers
+
+Operations depend on `LedgerSync::Adaptor::LedgerSerializer`s to serialize and deserialize objects.  Most resources have a default serializer per adaptor which may acts as both a serializer and deserializer.  You can provide custom serializers, which is necessary when working with custom attributes.  For example, given the following:
+- `custom_resource` that is a `LedgerSync::Customer` (see above)
+- the attribute `foo` is used in both the request and response bodies
+- using the `NetSuite` adaptor
+
+you could implement custom serializers using the following code:
+
+```ruby
+class CustomSerializer < LedgerSync::Adaptors::NetSuite::Customer::LedgerSerializer
+  attribute ledger_attribute: :foo,
+            resource_attribute: :foo,
+            deserialize: true, # optional, default: true
+            serialize: true # optional, default: true
+end
+
+# Serializing
+custom_resource = CustomCustomer.new(foo: 'asdf') # See above under Resources -> Custom Attributes
+serializer = CustomSerializer.new(resource: custom_resource)
+serializer.to_ledger_hash # => {"foo"=>"asdf"}
+
+# Deserializing
+deserialized_resource = serializer.deserialize(hash: { foo: 'qwerty' })
+deserialized_resource.foo # => 'qwerty'
+custom_resource.foo # => 'asdf'
+
+op = LedgerSync::Adaptors::NetSuite::Customer::Operations::Create.new(
+  adaptor: adaptor,
+  ledger_deserializer_class: CustomSerializer, # You must specify, though you could use a separate class
+  ledger_serializer_class: CustomSerializer,
+  resource: custom_resource
+)
+```
+
+Note that in the above example, we extend an existing customer serializer in the NetSuite adaptor.  In most cases, serializers have the following inheritance pattern: `LedgerSync::Adaptors::[ADAPTOR]::[RESOURCE]::LedgerSerializer <  LedgerSync::Adaptors::[ADAPTOR]::LedgerSerializer <  LedgerSync::Adaptors::LedgerSerializer`
+
+So in this example, it would be `LedgerSync::Adaptors::NetSuite::Customer::LedgerSerializer <  LedgerSync::Adaptors::NetSuite::LedgerSerializer <  LedgerSync::Adaptors::LedgerSerializer`.  The more specific the serializer, the more helper methods are available that are adaptor and/or resource specific.
+
 #### Operation
 
 Each adaptor defines operations that can be performed on specific resources (e.g. `Customer::Operations::Update`, `Payment::Operations::Create`).  The operation defines two key things:
@@ -117,6 +202,37 @@ Each adaptor defines operations that can be performed on specific resources (e.g
 
 Note: Adaptors may support different operations for each resource type.
 
+##### Contracts
+
+Contracts are dry-validation schemas, which determine if an operation can be performed.  You can create custom schemas and pass them to operations.  Assuming you have an `operation_class` variable and `foo` is an attribute of a `custom_resource` (see above) that is required to be a string, you can implement it with the following:
+
+```ruby
+class CustomContract < LedgerSync::Adaptors::Contract
+  params do
+    required(:foo).filled(:string)
+  end
+end
+
+# A valid case
+custom_resource = CustomResource.new(foo: 'asdf')
+op = operation_class.new(
+  adaptor: adaptor,
+  resource: resource,
+  validation_contract: CustomContract
+)
+op.valid? # => true
+
+# An invalid case
+custom_resource = CustomResource.new(foo: nil)
+operation_class.new(
+  adaptor: adaptor,
+  resource: resource,
+  validation_contract: CustomContract
+)
+op.valid? # => false
+
+```
+
 #### Searcher
 
 Searchers are used to search objects in the ledger.  A searcher takes an `adaptor`, `query` string and optional `pagination` hash.  For example, to search customer's by name:
@@ -330,26 +446,6 @@ The serialization of any object follows the same structure.  There is a `:root`
 }
 ```
 
-## Test Adaptor
-
-LedgerSync offers a test adaptor `LedgerSync::Adaptors::Test::Adaptor` that you can easily use and stub without requiring API requests.  For example:
-
-```ruby
-
-operation = LedgerSync::Adaptors::Test::Customer::Operations::Create.new(
-  adaptor: LedgerSync::Adaptors::Test::Adaptor.new,
-  resource: LedgerSync::Customer.new(name: 'Test Customer')
-)
-
-expect(operation).to be_valid
-
-result = operation.perform
-expect(result).to be_a(LedgerSync::OperationResult::Success)
-expect(result).to be_success
-
-expect { operation.perform }.to raise_error(PerformedOperationError)
-```
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.

data/ledger_sync.gemspec

@@ -50,6 +50,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency('netsuite')
   spec.add_runtime_dependency('nokogiri', '>= 0')
   spec.add_runtime_dependency('oauth2', '>= 0')
+  spec.add_runtime_dependency('pd_ruby', '>= 0')
   spec.add_runtime_dependency('resonad', '>= 0')
   spec.add_runtime_dependency('simply_serializable', '>= 1.3.0')
   spec.add_runtime_dependency('stripe')

data/lib/ledger_sync.rb

@@ -14,6 +14,7 @@ require 'stripe'
 require 'netsuite'
 require 'oauth2'
 require 'tempfile'
+require 'pd_ruby'
 
 # Dotenv
 require 'dotenv'
@@ -34,7 +35,6 @@ Gem.find_files('ledger_sync/error/**/*.rb').each { |path| require path }
 
 # Support Classes
 require 'ledger_sync/util/resonad'
-require 'ledger_sync/util/debug'
 require 'ledger_sync/util/signer'
 require 'ledger_sync/util/hash_helpers'
 require 'ledger_sync/util/resources_builder'

data/lib/ledger_sync/adaptors/ledger_serializer.rb

@@ -12,9 +12,8 @@ module LedgerSync
 
       attr_reader :resource
 
-      def initialize(ensure_inferred_resource_class: true, resource:)
-        @resource = resource
-        ensure_inferred_resource_class! if ensure_inferred_resource_class
+      def initialize(**keywords)
+        @resource = keywords.fetch(:resource)
       end
 
       def attribute_value_from_ledger(hash:, ledger_serializer_attribute:, resource:)
@@ -139,13 +138,6 @@ module LedgerSync
           type: type
         )
       end
-
-      private
-
-      def ensure_inferred_resource_class!
-        inferred_resource_class = self.class.inferred_resource_class
-        raise "Resource must be a #{inferred_resource_class.name}.  Given #{resource.class}" unless resource.is_a?(inferred_resource_class)
-      end
     end
   end
 end

data/lib/ledger_sync/adaptors/mixins/infer_ledger_serializer_mixin.rb

@@ -5,19 +5,33 @@ module LedgerSync
     module Mixins
       module InferLedgerSerializerMixin
         module ClassMethods
-          def inferred_ledger_serializer(resource:)
-            inferred_ledger_serializer_class.new(
-              resource: resource
-            )
+          def inferred_ledger_deserializer_class
+            @inferred_ledger_deserializer_class ||= begin
+              inferred_adaptor_class.base_module.const_get(
+                inferred_ledger_deserializer_class_name
+              )
+            rescue NameError
+              inferred_adaptor_class.base_module.const_get(
+                inferred_ledger_serializer_class_name
+              )
+            end
+          end
+
+          def inferred_ledger_deserializer_class_name
+            @inferred_ledger_deserializer_class_name ||= "#{inferred_resource_class.resource_module_str}::LedgerDeserializer"
           end
 
           def inferred_ledger_serializer_class
             @inferred_ledger_serializer_class ||= begin
               inferred_adaptor_class.base_module.const_get(
-                "#{inferred_resource_class.resource_module_str}::LedgerSerializer"
+                inferred_ledger_serializer_class_name
               )
             end
           end
+
+          def inferred_ledger_serializer_class_name
+            @inferred_ledger_serializer_class_name ||= "#{inferred_resource_class.resource_module_str}::LedgerSerializer"
+          end
         end
 
         def self.included(base)

data/lib/ledger_sync/adaptors/mixins/infer_validation_contract_mixin.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module LedgerSync
+  module Adaptors
+    module Mixins
+      module InferValidationContractMixin
+        module ClassMethods
+          def inferred_validation_contract_class
+            @inferred_validation_contract_class ||= begin
+              const_get(
+                inferred_validation_contract_class_name
+              )
+            end
+          end
+
+          def inferred_validation_contract_class_name
+            @inferred_validation_contract_class_name ||= "#{name}::Contract"
+          end
+        end
+
+        def self.included(base)
+          base.extend ClassMethods
+        end
+      end
+    end
+  end
+end

data/lib/ledger_sync/adaptors/netsuite/config.rb

@@ -2,5 +2,4 @@
 
 LedgerSync.register_adaptor(:netsuite, module_string: 'NetSuite') do |config|
   config.name = 'NetSuite REST'
-  config.rate_limiting_wait_in_seconds = 60
 end

data/lib/ledger_sync/adaptors/netsuite/operation.rb

@@ -11,12 +11,6 @@ module LedgerSync
           end
 
           module InstanceMethods
-            def ledger_deserializer
-              @ledger_deserializer ||= begin
-                modules = self.class.name.split('::Operations::').first
-                Object.const_get("#{modules}::LedgerDeserializer").new(resource: resource)
-              end
-            end
           end
         end
       end

data/lib/ledger_sync/adaptors/operation.rb

@@ -3,8 +3,6 @@
 module LedgerSync
   module Adaptors
     module Operation
-      TYPES = %i[create delete find update].freeze
-
       module Mixin
         module ClassMethods
           def adaptor_klass
@@ -14,95 +12,63 @@ module LedgerSync
           def operations_module
             @operations_module ||= Object.const_get(name.split('::Operations::').first + '::Operations')
           end
-
-          def resource_klass
-            @resource_klass ||= LedgerSync.const_get(
-              name
-                .split("#{adaptor_klass.config.base_module.name}::")
-                .last
-                .split('::Operations')
-                .first
-            )
-          end
         end
 
         def self.included(base)
           base.include SimplySerializable::Mixin
           base.include Fingerprintable::Mixin
+          base.include Error::HelpersMixin
           base.include Adaptors::Mixins::InferLedgerSerializerMixin
+          base.include Adaptors::Mixins::InferValidationContractMixin
           base.extend ClassMethods
 
           base.class_eval do
             serialize only: %i[
-                        adaptor
-                        after_operations
-                        before_operations
-                        operations
-                        resource
-                        root_operation
-                        result
-                        response
-                        original
-                      ]
+              adaptor
+              resource
+              result
+              response
+            ]
           end
         end
 
         attr_reader :adaptor,
-                    :after_operations,
-                    :before_operations,
-                    :operations,
                     :resource,
                     :resource_before_perform,
-                    :root_operation,
                     :result,
-                    :response,
-                    :original
-
-        def initialize(adaptor:, resource:)
-          raise 'Missing adaptor' if adaptor.nil?
-          raise 'Missing resource' if resource.nil?
+                    :response
 
-          raise "#{resource.class.name} is not a valid resource type.  Expected #{self.class.resource_klass.name}" unless resource.is_a?(self.class.resource_klass)
-
-          @adaptor = adaptor
-          @after_operations = []
-          @before_operations = []
-          @operations = []
-          @resource = resource
+        def initialize(
+          **keywords
+        )
+          @adaptor = keywords.fetch(:adaptor)
+          @ledger_deserializer_class = keywords.fetch(:ledger_deserializer_class, nil)
+          @ledger_serializer_class = keywords.fetch(:ledger_serializer_class, nil)
+          @resource = keywords.fetch(:resource)
           @resource_before_perform = resource.dup
           @result = nil
-          @root_operation = nil
-        end
+          @validation_contract = keywords.fetch(:validation_contract, nil)
 
-        def add_after_operation(operation)
-          @operations << operation
-          @after_operations << operation
-        end
-
-        def add_before_operation(operation)
-          @operations << operation
-          @before_operations << operation
-        end
-
-        def add_root_operation(operation)
-          @operations << operation
-          @root_operation = operation
+          self.class.raise_if_unexpected_class(expected: self.class.inferred_resource_class, given: @resource.class)
+          self.class.raise_if_unexpected_class(expected: LedgerSync::Adaptors::LedgerSerializer, given: ledger_deserializer_class) unless @ledger_deserializer_class.nil?
+          self.class.raise_if_unexpected_class(expected: LedgerSync::Adaptors::LedgerSerializer, given: ledger_serializer_class) unless @ledger_serializer_class.nil?
+          self.class.raise_if_unexpected_class(expected: LedgerSync::Adaptors::Contract, given: validation_contract) unless @validation_contract.nil?
         end
 
         def perform
           failure(LedgerSync::Error::OperationError::PerformedOperationError.new(operation: self)) if @performed
 
-          begin
+          @result = begin
             operate
-          rescue LedgerSync::Error => e
-            failure(e)
-          rescue StandardError => e
-            parsed_error = adaptor.parse_operation_error(error: e, operation: self)
-            raise e unless parsed_error
-
-            failure(parsed_error)
-          ensure
-            @performed = true
+                    rescue LedgerSync::Error => e
+                      failure(e)
+                    rescue StandardError => e
+                      parsed_error = adaptor.parse_operation_error(error: e, operation: self)
+                      raise e unless parsed_error
+
+                      failure(parsed_error)
+                    ensure
+                      @performed = true
           end
         end
 
@@ -110,8 +76,20 @@ module LedgerSync
           @performed == true
         end
 
+        def ledger_deserializer
+          ledger_deserializer_class.new(resource: resource)
+        end
+
+        def ledger_deserializer_class
+          @ledger_deserializer_class ||= self.class.inferred_ledger_deserializer_class
+        end
+
         def ledger_serializer
-          self.class.inferred_ledger_serializer(resource: resource)
+          ledger_serializer_class.new(resource: resource)
+        end
+
+        def ledger_serializer_class
+          @ledger_serializer_class ||= self.class.inferred_ledger_serializer_class
         end
 
         # Results
@@ -149,14 +127,16 @@ module LedgerSync
         end
 
         def validate
-          raise "#{self.class.name}::Contract must be defined to validate." unless self.class.const_defined?('Contract')
-
           Util::Validator.new(
-            contract: self.class::Contract,
+            contract: validation_contract,
             data: validation_data
           ).validate
         end
 
+        def validation_contract
+          @validation_contract ||= self.class.inferred_validation_contract_class
+        end
+
         def validation_data
           serializer = resource.serializer(
             do_not_serialize_if_class_is: Resource::PRIMITIVES
@@ -177,14 +157,6 @@ module LedgerSync
           true
         end
 
-        # Type Methods
-
-        TYPES.each do |type|
-          define_method "#{type.to_s.downcase}?" do
-            false
-          end
-        end
-
         private
 
         def operate
@@ -192,17 +164,6 @@ module LedgerSync
         end
       end
 
-      TYPES.each do |type|
-        klass = Class.new do
-          include Operation::Mixin
-
-          define_method("#{type.to_s.downcase}?") do
-            true
-          end
-        end
-        Operation.const_set(LedgerSync::Util::StringHelpers.camelcase(type.to_s), klass)
-      end
-
       def self.klass_from(adaptor:, method:, object:)
         adaptor.base_module.const_get(
           LedgerSync::Util::StringHelpers.camelcase(object)