ledger_sync 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3da74afb88bc320a1a36c19cb72346d4c5fdd4055de62a4a8393879e3f70fcb5
-  data.tar.gz: 6602d10e2339ee87831fc33b11fcd4d305a79a733aa4a67225ae1c6d30977fdd
+  metadata.gz: e777a594ee4da7c59da77df28dbb9d39dae0988cbcc8a0b8af5e82371e29ab11
+  data.tar.gz: 9df2f22c0b7001e077b8d03e934145ffdc58b91051ab32e2a581a86c16b40ce9
 SHA512:
-  metadata.gz: bc29df605f6f79baa17f5a9e798c82c70c602bca83aac6b4e5427b7f46ac8f8990d893fc5b9015678a5bb658ac35bbc7663e24a71aff922e4c06d77da76382c4
-  data.tar.gz: e6f250ee6a0821ee8691766c5f4eaa016889ec90173442c1c68b6481395a65f81f24817ebbc0fc04747de4902951472c3a6e4200280e7db12cd3ffdcaa351813
+  metadata.gz: 48b90e5bf88b16b92bb6d365070d1f8ea4011f50db62e82bf9a8dd19cc2a03106bfe56ba117a2a0a8806fb02866e1a6ccfcb3b75332c0b2fc4969920098b2821
+  data.tar.gz: b274ef24289ae0de509fc3ce6222e481a5ec43bffcfd7c2066c1baf1bac00edb63552206c3e35c180ba5fe1f77b58fe5f8b602f3940538e97edffff14b278cb9

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

data/.gitignore

@@ -9,3 +9,7 @@
 
 # rspec failure tracking
 .rspec_status
+
+.byebug_history
+
+.DS_Store

data/.rubocop.yml

@@ -0,0 +1,4 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 2.6

data/.rubocop_todo.yml

@@ -0,0 +1,25 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2019-03-29 13:21:38 +0100 using RuboCop version 0.66.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+Metrics/AbcSize:
+  Enabled: False
+
+Metrics/BlockLength:
+  Enabled: False
+
+Style/Documentation:
+  Enabled: False
+
+Metrics/LineLength:
+  Enabled: False
+
+Metrics/MethodLength:
+  Enabled: False
+
+Metrics/ParameterLists:
+  Enabled: False

data/.travis.yml

@@ -3,5 +3,5 @@ sudo: false
 language: ruby
 cache: bundler
 rvm:
-  - 2.6.2
+  - 2.5.1
 before_install: gem install bundler -v 2.0.1

data/Dockerfile

@@ -0,0 +1,8 @@
+FROM ruby:2.5.1
+
+WORKDIR /lib
+
+COPY . .
+RUN bundle install
+
+CMD ["bundle", "exec", "rspec"]

data/Gemfile

@@ -1,4 +1,6 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in ledger_sync.gemspec
 gemspec

data/Gemfile.lock

@@ -1,35 +1,164 @@
 PATH
   remote: .
   specs:
-    ledger_sync (0.1.0)
+    ledger_sync (1.0.0)
+      colorize
+      coveralls
+      dry-schema
+      dry-validation
+      faraday
+      faraday-detailed_logger
+      faraday_middleware
+      fingerprintable (>= 1.2.1)
+      nokogiri
+      oauth2
+      resonad
+      simply_serializable (>= 1.3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.6.0)
+      public_suffix (>= 2.0.2, < 4.0)
+    ast (2.4.0)
+    awesome_print (1.8.0)
+    bump (0.8.0)
+    byebug (11.0.1)
+    colorize (0.8.1)
+    concurrent-ruby (1.1.5)
+    coveralls (0.8.23)
+      json (>= 1.8, < 3)
+      simplecov (~> 0.16.1)
+      term-ansicolor (~> 1.3)
+      thor (>= 0.19.4, < 2.0)
+      tins (~> 1.6)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
     diff-lcs (1.3)
+    docile (1.3.2)
+    dry-configurable (0.8.3)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.4, >= 0.4.7)
+    dry-container (0.7.2)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 0.1, >= 0.1.3)
+    dry-core (0.4.8)
+      concurrent-ruby (~> 1.0)
+    dry-equalizer (0.2.2)
+    dry-inflector (0.1.2)
+    dry-initializer (3.0.1)
+    dry-logic (1.0.2)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.2)
+      dry-equalizer (~> 0.2)
+    dry-schema (1.3.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.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.0)
+      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)
+      multipart-post (>= 1.2, < 3)
+    faraday-detailed_logger (2.1.3)
+      faraday (~> 0.8)
+    faraday_middleware (0.13.1)
+      faraday (>= 0.7.4, < 1.0)
+    fingerprintable (1.2.1)
+      colorize
+    hashdiff (0.4.0)
+    jaro_winkler (1.5.2)
+    json (2.2.0)
+    jwt (2.2.1)
+    mini_portile2 (2.4.0)
+    multi_json (1.13.1)
+    multi_xml (0.6.0)
+    multipart-post (2.1.1)
+    nokogiri (1.10.3)
+      mini_portile2 (~> 2.4.0)
+    oauth2 (1.4.1)
+      faraday (>= 0.8, < 0.16.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)
+      ast (~> 2.4.0)
+    public_suffix (3.1.0)
+    rack (2.0.7)
+    rainbow (3.0.0)
     rake (10.5.0)
+    resonad (1.2.0)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
       rspec-expectations (~> 3.8.0)
       rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.0)
+    rspec-core (3.8.2)
       rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.3)
+    rspec-expectations (3.8.4)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.0)
+    rspec-mocks (3.8.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
-    rspec-support (3.8.0)
+    rspec-support (3.8.2)
+    rubocop (0.71.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.6)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    ruby-progressbar (1.10.1)
+    safe_yaml (1.0.5)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    simply_serializable (1.3.0)
+      fingerprintable (>= 1.2.1)
+    term-ansicolor (1.7.1)
+      tins (~> 1.0)
+    thor (0.20.3)
+    tins (1.21.0)
+    unicode-display_width (1.6.0)
+    vcr (5.0.0)
+    webmock (3.6.0)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 2.0)
+  awesome_print
+  bump
+  bundler (~> 1.16)
+  byebug
   ledger_sync!
   rake (~> 10.0)
-  rspec (~> 3.0)
+  rspec (~> 3.2)
+  rubocop
+  vcr
+  webmock
 
 BUNDLED WITH
-   2.0.1
+   1.17.2

data/README.md

@@ -1,10 +1,8 @@
 # LedgerSync
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/ledger_sync`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Build Status](https://travis-ci.org/LedgerSync/ledger_sync.svg?branch=master)](https://travis-ci.org/LedgerSync/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)
 
-TODO: Delete this and the text above, and describe your gem
-
-## Installation
+# Installation
 
 Add this line to your application's Gemfile:
 
@@ -20,19 +18,196 @@ 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:
+
+```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
+)
+
+sync.operations # Returns the ordered list of operations to be performed
+
+sync.perform # Returns a SyncResult (either ::Success or ::Failure)
+```
+
+**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.**
+
+# How it Works
+
+## The Library Structure
+
+This library consists of two important layers:
+
+1. Resources
+2. Adaptors
+
+### 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.
+
+You can find supported resources by calling `LedgerSync.resources`.
+
+Resources have defined attributes.  Attributes are explicitly defined.  An error is thrown if an unknown attribute is passed to it.  You can retrieve the attributes of a resource by calling `LedgerSync::Customer.attributes`.
+
+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 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
+- operations
+- searchers
+
+### Adaptor
+
+The adaptor handles authentication and requests to the ledger.  Each adaptors initializer will vary based on the needs of that ledger.
+
+### Operation
+
+Each adaptor defines operations that can be performed on specific resources (e.g. `Customer::Update`, `Payment::Create`).  The operation defines three 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
+
+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.
+
+# Tips and More!
 
-TODO: Write usage instructions here
+## Keywords
 
-## Development
+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)`.
+
+## Fingerprints
+
+Most objects in LedgerSync can be fingerprinted by calling the instance method `fingerprint`.  For example:
+
+```ruby
+puts LedgerSync::Customer.new.fingerprint # "b3eab7ec00431a4ae0468fee72e5ba8f"
+
+puts LedgerSync::Customer.new.fingerprint == LedgerSync::Customer.new.fingerprint # true
+puts LedgerSync::Customer.new.fingerprint == LedgerSync::Customer.new(name: :foo).fingerprint # false
+puts LedgerSync::Customer.new.fingerprint == LedgerSync::Payment.new.fingerprint # false
+```
+
+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
+
+Most objects in LedgerSync can be serialized by calling the instance method `serialize`.  For example:
+
+```ruby
+puts LedgerSync::Payment.new(
+  customer: LedgerSync::Customer.new
+)
+
+{
+  root: "LedgerSync::Payment/8eed81c0177801a001f2544f0c85e21d",
+  objects: {
+    "LedgerSync::Payment/8eed81c0177801a001f2544f0c85e21d": {
+      id: "LedgerSync::Payment/8eed81c0177801a001f2544f0c85e21d",
+      object: "LedgerSync::Payment",
+      fingeprint: "8eed81c0177801a001f2544f0c85e21d",
+      data: {
+        currency: nil,
+        amount: nil,
+        customer: {
+          object: "reference",
+          id: "LedgerSync::Customer/b3eab7ec00431a4ae0468fee72e5ba8f"
+        },
+        external_id: "",
+        ledger_id: nil,
+        sync_token: nil
+      }
+    },
+    "LedgerSync::Customer/b3eab7ec00431a4ae0468fee72e5ba8f": {
+      id: "LedgerSync::Customer/b3eab7ec00431a4ae0468fee72e5ba8f",
+      object: "LedgerSync::Customer",
+      fingeprint: "b3eab7ec00431a4ae0468fee72e5ba8f",
+      data: {
+        name: nil,
+        email: nil,
+        phone_number: nil,
+        external_id: "",
+        ledger_id: nil,
+        sync_token: nil
+      }
+    }
+  }
+}
+```
+
+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:
+
+```ruby
+{
+  object: "reference",
+  id: "LedgerSync::Customer/b3eab7ec00431a4ae0468fee72e5ba8f"
+}
+```
+
+# Testing
+
+LedgerSync offers a test adaptor `LedgerSync::Adaptors::Test` 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
+)
+
+expect(sync.perform).to be_a(LedgerSync::SyncResult::Success)
+```
+
+# 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.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+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
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/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.
+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
 
@@ -40,4 +215,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## 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/[USERNAME]/ledger_sync/blob/master/CODE_OF_CONDUCT.md).
+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).