ledger_sync 1.0.10 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd00a20c0fc0e5fa31901cbc8470e7081e629fefab4bf451408f05fdca1879c0
-  data.tar.gz: 6302b8e87ccbf4716b31e63a68add132a80145b7758834feb89215b6210dd770
+  metadata.gz: 9bf08ab386468485d8e81f3e40d43ca41664d69e4a09d1e70f658e047f82295d
+  data.tar.gz: 69a554102281aae008333eeea328691bcc242417152e3fe6e2ddfca726a7cb7c
 SHA512:
-  metadata.gz: 58aa1ea5129d57709a808a95ec0da2a193e3d87430c75bb72036c9e12b2b84779a7a2a2dcd82656612c3d962479baa4d17122a9eb42caff7dfd2ee0ae884c998
-  data.tar.gz: 7919f3da5948ca70bb04fa51b0e1eea3d16ba0f81cbc20d9a94bac5aaf58fe6aa70b1d1b6bb5151bb8002db12e451c5b96d2d638b7a784d863d471cd719d5ef3
+  metadata.gz: ac04c1f2fc9fc9fb06443ad61a3f28e3ca102f1bd70d0c8c693549f2a9e75d83b4ad4fc10e5ed476b31038cd0190b6a077f9b3fefa02d629a15746a23e4e6647
+  data.tar.gz: 7b282b14b77360effae62f6b3f4c36c3f067a0d29f5bd721686c80460784943304a42c01cae1336aaf0dd6fc7803f39e63868ea38fce900150385f3b43ff969c

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    ledger_sync (1.0.10)
+    ledger_sync (1.1.1)
+      activemodel
       colorize
       coveralls
       dry-schema
@@ -18,8 +19,16 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.6.0)
-      public_suffix (>= 2.0.2, < 4.0)
+    activemodel (6.0.0)
+      activesupport (= 6.0.0)
+    activesupport (6.0.0)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.1, >= 2.1.8)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
     ast (2.4.0)
     awesome_print (1.8.0)
     bump (0.8.0)
@@ -42,38 +51,38 @@ GEM
     dry-container (0.7.2)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 0.1, >= 0.1.3)
-    dry-core (0.4.8)
+    dry-core (0.4.9)
       concurrent-ruby (~> 1.0)
     dry-equalizer (0.2.2)
-    dry-inflector (0.1.2)
+    dry-inflector (0.2.0)
     dry-initializer (3.0.1)
-    dry-logic (1.0.2)
+    dry-logic (1.0.3)
       concurrent-ruby (~> 1.0)
       dry-core (~> 0.2)
       dry-equalizer (~> 0.2)
-    dry-schema (1.3.1)
+    dry-schema (1.4.1)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 0.8, >= 0.8.3)
       dry-core (~> 0.4)
       dry-equalizer (~> 0.2)
       dry-initializer (~> 3.0)
       dry-logic (~> 1.0)
-      dry-types (~> 1.0)
-    dry-types (1.1.1)
+      dry-types (~> 1.2)
+    dry-types (1.2.0)
       concurrent-ruby (~> 1.0)
       dry-container (~> 0.3)
       dry-core (~> 0.4, >= 0.4.4)
       dry-equalizer (~> 0.2, >= 0.2.2)
       dry-inflector (~> 0.1, >= 0.1.2)
       dry-logic (~> 1.0, >= 1.0.2)
-    dry-validation (1.2.1)
+    dry-validation (1.3.1)
       concurrent-ruby (~> 1.0)
       dry-container (~> 0.7, >= 0.7.1)
       dry-core (~> 0.4)
       dry-equalizer (~> 0.2)
       dry-initializer (~> 3.0)
       dry-schema (~> 1.0, >= 1.3.1)
-    faraday (0.15.4)
+    faraday (0.17.0)
       multipart-post (>= 1.2, < 3)
     faraday-detailed_logger (2.1.3)
       faraday (~> 0.8)
@@ -82,25 +91,28 @@ GEM
     fingerprintable (1.2.1)
       colorize
     hashdiff (1.0.0)
+    i18n (1.7.0)
+      concurrent-ruby (~> 1.0)
     jaro_winkler (1.5.3)
     json (2.2.0)
     jwt (2.2.1)
     mini_portile2 (2.4.0)
-    multi_json (1.13.1)
+    minitest (5.12.2)
+    multi_json (1.14.1)
     multi_xml (0.6.0)
     multipart-post (2.1.1)
-    nokogiri (1.10.3)
+    nokogiri (1.10.4)
       mini_portile2 (~> 2.4.0)
-    oauth2 (1.4.1)
-      faraday (>= 0.8, < 0.16.0)
+    oauth2 (1.4.2)
+      faraday (>= 0.8, < 2.0)
       jwt (>= 1.0, < 3.0)
       multi_json (~> 1.3)
       multi_xml (~> 0.5)
       rack (>= 1.2, < 3)
     parallel (1.17.0)
-    parser (2.6.3.0)
+    parser (2.6.4.1)
       ast (~> 2.4.0)
-    public_suffix (3.1.1)
+    public_suffix (4.0.1)
     rack (2.0.7)
     rainbow (3.0.0)
     rake (10.5.0)
@@ -118,7 +130,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
     rspec-support (3.8.2)
-    rubocop (0.73.0)
+    rubocop (0.74.0)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
       parser (>= 2.6)
@@ -132,18 +144,22 @@ GEM
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
-    simply_serializable (1.3.0)
+    simply_serializable (1.4.2)
       fingerprintable (>= 1.2.1)
     term-ansicolor (1.7.1)
       tins (~> 1.0)
     thor (0.20.3)
+    thread_safe (0.3.6)
     tins (1.21.1)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
     unicode-display_width (1.6.0)
     vcr (5.0.0)
-    webmock (3.6.0)
+    webmock (3.7.5)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    zeitwerk (2.2.0)
 
 PLATFORMS
   ruby

data/README.md

@@ -4,7 +4,7 @@
 [![Gem Version](https://badge.fury.io/rb/ledger_sync.svg)](https://badge.fury.io/rb/ledger_sync)
 [![Coverage Status](https://coveralls.io/repos/github/LedgerSync/ledger_sync/badge.svg?branch=master)](https://coveralls.io/github/LedgerSync/ledger_sync?branch=master)
 
-# Installation
+## Installation
 
 Add this line to your application's Gemfile:
 
@@ -20,36 +20,69 @@ Or install it yourself as:
 
     $ gem install ledger_sync
 
-# Usage
+## Usage
 
-The easiest entry point into the library is the `Sync` class, which will handle building, validating, and performing all the necessary operations to sync an object.  You can of course build and manage these primitives yourself if you require more control.  Here is an example of a sync:
+To use LedgerSync, you must create an `Operation`.  The operation will be ledger-specific and will require the following:
+
+1. Adaptor
+2. Resource(s)
+
+The code may look like the following:
 
 ```ruby
-sync = LedgerSync::Sync.new(
-  adaptor: adaptor, # The adaptor for the ledger you want to use (see below)
-  method: :upsert,
-  resources_data: resources_data, # The structured hash of resource data (see below)
-  resource_external_id: resource_external_id, # The root object ID on which the operation is to be performed
-  resource_type: resource_type # The root object type on which the operation is to be performed
+# First we create an adaptor, which is our connection to a ledger.
+# Each ledger may require different keys, so check the
+# documentation below for specifics.
+adaptor = LedgerSync::Adaptors::QuickBooksOnline::Adaptor.new(
+  access_token: access_token, # assuming this is defined
+  client_id: ENV['QUICKBOOKS_ONLINE_CLIENT_ID'],
+  client_secret: ENV['QUICKBOOKS_ONLINE_CLIENT_SECRET'],
+  realm_id: ENV['QUICKBOOKS_ONLINE_REALM_ID'],
+  refresh_token: refresh_token, # assuming this is defined
 )
 
-sync.operations # Returns the ordered list of operations to be performed
+# Create a resource on which to operate.  Some resources have
+# relationships with other resources.  You can use
+# `Util::ResourcesBuilder` to create resources and relationships from
+# a structured hash.
+resource = LedgerSync::Customer.new(
+  name: 'Sample Customer',
+  email: 'test@example.com'
+)
 
-sync.perform # Returns a SyncResult (either ::Success or ::Failure)
-```
+# Create the operation we want to perform.
+operation = LedgerSync::Adaptors::QuickBooksOnline::Customer::Operations::Create.new(
+  adaptor: adaptor,
+  resource: resource
+)
 
-**NOTE: Even when not performing the sync (`sync.perform`) and just retrieving the operations (`sync.operations`), the library will make API requests to the ledger in order to determine if a `create` or `update` is necessary for each object involved.**
+result = operation.perform # Returns a LedgerSync::OperationResult
+
+if result.success?
+  resource = result.operation.resource
+  # Do something with resource
+else # result.failure?
+  raise result.error
+end
+
+# Because QuickBooks Online uses Oauth 2, you must always be sure to
+# save the access_token, refresh_token, and expirations as they can
+# change with any API call.
+result.operation.adaptor.ledger_attributes_to_save.each do |key, value|
+  # save values
+end
+```
 
-# How it Works
+## How it Works
 
-## The Library Structure
+### 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.
 
@@ -59,7 +92,7 @@ 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`.
 
-## Adaptors
+### 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:
 
@@ -67,31 +100,57 @@ Adaptors are ledger-specific ruby objects that contain all the logic to authenti
 - operations
 - searchers
 
-### Adaptor
+#### Adaptor
 
 The adaptor handles authentication and requests to the ledger.  Each adaptors initializer will vary based on the needs of that ledger.
 
-### Operation
+#### Operation
 
-Each adaptor defines operations that can be performed on specific resources (e.g. `Customer::Update`, `Payment::Create`).  The operation defines three key things:
+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:
 
 - a `Contract` class which is used to validate the resource using the `dry-validation` gem
-- a `build` instance method, which handles any pre-processing to be done before the operation is performed (e.g. converting an `Upsert` into a `Create` or `Update`)
 - a `perform` instance method, which handles the actual API requests and response/error handling.
 
 Note: Adaptors may support different operations for each resource type.
 
-### Searcher
+#### 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:
+
+```ruby
+searcher = LedgerSync::Adaptors::QuickBooksOnline::Customer::Searcher.new(
+  adaptor: adaptor # assuming this is defined,
+  query: 'test'
+)
+
+result = searcher.search # returns a LedgerSync::SearchResult
+
+if result.success?
+  resources = result.resources
+  # Do something with found resources
+else # result.failure?
+  raise result.error
+end
 
-Searchers are a classes that make it easy to search objects in the ledger.  A searcher takes an `adaptor`, `query` string and optional `pagination` hash.
+# Different ledgers may use different pagination strategies.  In order
+# to get the next and previous set of results, you can use the following:
+next_searcher = searcher.next_searcher
+previous_searcher = searcher.previous_searcher
+```
+
+## QuickBooks Online
 
-# Tips and More!
+### Errors
+
+https://developer.intuit.com/app/developer/qbo/docs/develop/troubleshooting/error-codes
 
-## Keywords
+## Tips and More!
 
-LedgerSync heavily uses ruby keywords so as to make it clear what values are being passed and which attributes are required.  When this README says something like "the `fun_function` function takes the argument `foo`" that translates to `fun_function(foo: :some_value)`.
+### Keyword Arguments
 
-## Fingerprints
+LedgerSync heavily uses ruby keyword arguments so as to make it clear what values are being passed and which attributes are required.  When this README says something like "the `fun_function` function takes the argument `foo`" that translates to `fun_function(foo: :some_value)`.
+
+### Fingerprints
 
 Most objects in LedgerSync can be fingerprinted by calling the instance method `fingerprint`.  For example:
 
@@ -105,7 +164,7 @@ puts LedgerSync::Customer.new.fingerprint == LedgerSync::Payment.new.fingerprint
 
 Fingerprints are used to compare objects.  This method is used in de-duping objects, as it only considers the data inside and not the instance itself (as shown above).
 
-## Serialization
+### Serialization
 
 Most objects in LedgerSync can be serialized by calling the instance method `serialize`.  For example:
 
@@ -150,7 +209,7 @@ puts LedgerSync::Payment.new(
 }
 ```
 
-The serialization of any object follows the same struction.  There is a `:root` key that holds the ID of the root object.  There is also an `:objects` hash that contains all of the objects for this serialization.  As you can see, unique nested objects listed in the `:objects` hash and referenced using a "reference object", in this case:
+The serialization of any object follows the same structure.  There is a `:root` key that holds the ID of the root object.  There is also an `:objects` hash that contains all of the objects for this serialization.  As you can see, unique nested objects listed in the `:objects` hash and referenced using a "reference object", in this case:
 
 ```ruby
 {
@@ -159,32 +218,27 @@ The serialization of any object follows the same struction.  There is a `:root`
 }
 ```
 
-# Testing
+## Testing
 
-LedgerSync offers a test adaptor `LedgerSync::Adaptors::Test` that you can easily use and stub without requiring API requests.  For example:
+LedgerSync offers a test adaptor `LedgerSync::Adaptors::Test::Adaptor` that you can easily use and stub without requiring API requests.  For example:
 
 ```ruby
-resources_data = {
-  {
-    customer: {
-      'cus_1': {
-        name: 'Jane Doe'
-      }
-    }
-  }
-}
-sync = LedgerSync::Sync.new(
-  adaptor: LedgerSync::Adaptors::Test.new,
-  method: :upsert,
-  resources_data: resources_data,
-  resource_external_id: 'cus_1',
-  resource_type: :customer
+
+operation = LedgerSync::Adaptors::Test::Customer::Operations::Create.new(
+  adaptor: LedgerSync::Adaptors::Test::Adaptor.new,
+  resource: LedgerSync::Customer.new(name: 'Test Customer')
 )
 
-expect(sync.perform).to be_a(LedgerSync::SyncResult::Success)
+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
+## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
@@ -192,29 +246,14 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Run `bundle console` to start and interactive console with the library already loaded.
 
-### Adding an Adaptor
-
-## Errors
-
-https://developer.intuit.com/app/developer/qbo/docs/develop/troubleshooting/error-codes
-
-#### Directory Structure
-
-/quickbooks_online/
-  adaptor.rb
-  operations/
-    customer/
-      operation.rb
-
-
-## Contributing
+### Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/LedgerSync/ledger_sync. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-## License
+### License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## Code of Conduct
+### Code of Conduct
 
 Everyone interacting in the LedgerSync project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/LedgerSync/ledger_sync/blob/master/CODE_OF_CONDUCT.md).

data/ledger_sync.gemspec

@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency('rubocop', '>= 0')
   spec.add_development_dependency('vcr', '>= 0')
   spec.add_development_dependency('webmock', '>= 0')
+  spec.add_runtime_dependency('activemodel', '>= 0')
   spec.add_runtime_dependency('colorize', '>= 0')
   spec.add_runtime_dependency('coveralls')
   spec.add_runtime_dependency('dry-schema')

data/lib/ledger_sync.rb

@@ -9,6 +9,7 @@ require 'uri'
 require 'colorize'
 require 'fingerprintable'
 require 'simply_serializable'
+require 'active_model'
 
 # Version
 require 'ledger_sync/version'
@@ -29,7 +30,6 @@ require 'ledger_sync/util/hash_helpers'
 require 'ledger_sync/util/resources_builder'
 require 'ledger_sync/adaptor_configuration'
 require 'ledger_sync/adaptor_configuration_store'
-require 'ledger_sync/util/coordinator'
 require 'ledger_sync/util/performer'
 require 'ledger_sync/util/validator'
 require 'ledger_sync/util/string_helpers'
@@ -39,11 +39,19 @@ require 'ledger_sync/adaptors/contract'
 
 # Resources (resources are registerd below)
 require 'ledger_sync/resource' # Template class
+require 'ledger_sync/resources/account'
 require 'ledger_sync/resources/customer'
+require 'ledger_sync/resources/vendor'
 require 'ledger_sync/resources/payment'
-
-# Synchronizer
-require 'ledger_sync/sync'
+require 'ledger_sync/resources/expense_line_item'
+require 'ledger_sync/resources/expense'
+require 'ledger_sync/resources/deposit_line_item'
+require 'ledger_sync/resources/deposit'
+require 'ledger_sync/resources/transfer'
+require 'ledger_sync/resources/bill_line_item'
+require 'ledger_sync/resources/bill'
+require 'ledger_sync/resources/journal_entry_line_item'
+require 'ledger_sync/resources/journal_entry'
 
 module LedgerSync
   @log_level = nil
@@ -106,5 +114,16 @@ end
 Gem.find_files('ledger_sync/adaptors/**/config.rb').each { |path| require path }
 
 # Register Resources
+LedgerSync.register_resource(resource: LedgerSync::Account)
 LedgerSync.register_resource(resource: LedgerSync::Customer)
+LedgerSync.register_resource(resource: LedgerSync::Vendor)
 LedgerSync.register_resource(resource: LedgerSync::Payment)
+LedgerSync.register_resource(resource: LedgerSync::ExpenseLineItem)
+LedgerSync.register_resource(resource: LedgerSync::Expense)
+LedgerSync.register_resource(resource: LedgerSync::DepositLineItem)
+LedgerSync.register_resource(resource: LedgerSync::Deposit)
+LedgerSync.register_resource(resource: LedgerSync::Transfer)
+LedgerSync.register_resource(resource: LedgerSync::BillLineItem)
+LedgerSync.register_resource(resource: LedgerSync::Bill)
+LedgerSync.register_resource(resource: LedgerSync::JournalEntryLineItem)
+LedgerSync.register_resource(resource: LedgerSync::JournalEntry)