ledger_sync 1.3.2 → 1.4.1

data/documentation/site/blog/index.md

@@ -0,0 +1,6 @@
+---
+title: Blog
+subtitle: This is an optional subtitle for the blog page
+image: images/5.jpg
+layout: blog
+---

data/documentation/site/guides/architecture/clients.md

@@ -0,0 +1,35 @@
+---
+title: Clients
+weight: 1
+layout: guides
+---
+
+## Overview
+
+Clients handle the authentication and requests to the ledger.  A ledger may have different authentication strategies,
+so clients will accept different arguments.  For example, QuickBooks Online utilizes Oauth 2.0 while NetSuite offers
+Token Based Authentication.  While similar, the required keys are different.
+
+## How to use
+
+Unless you are customizing LedgerSync, you will always pass an instantiated client to an object (e.g. an operation).
+The object will handle using the client as needed.
+
+As most clients implement basic request functionality (e.g. `get`, `put`, `post`, `delete`, etc.), you can call these methods directly to perform custom requests.  Refer to the specific Client definitions for what parameters are permitted.
+
+## Gotchas
+
+### Oauth 2.0
+
+Clients store the authentication details for the ledger.  Given that Oauth 2.0 tokens can refresh during a request,
+these clients will handle saving credentials back to the client instance.  Typically (though some clients offer
+more automated solutions), you will want to save any changes back to your database.  You can use
+`client.ledger_attributes_to_save` to retrieve a hash of which attributes to save. Your code to do so could look like
+the following:
+
+{% highlight ruby linenos %}
+# Assuming `client` is defined as an instance of a ledger Client class
+client.ledger_attributes_to_save.each do |attribute_to_save, value|
+  # Store value
+end
+{% endhighlight %}

data/documentation/site/guides/architecture/index.md

@@ -0,0 +1,14 @@
+---
+title: Architecture
+excerpt: Understand the high-level architecture of LedgerSync.
+layout: guides
+---
+
+LedgerSync consists of the following high-level objects:
+
+- [Clients](/guides/architecture/clients)
+- [Resources](/guides/architecture/resources)
+- [Serialization](/guides/architecture/serialization)
+- [Operations](/guides/architecture/operations)
+- [Searchers](/guides/architecture/searchers)
+- [Results](/guides/architecture/results)

data/documentation/site/guides/architecture/operations.md

@@ -0,0 +1,45 @@
+---
+title: Operations
+weight: 4
+layout: guides
+---
+
+Each ledger 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 `perform` instance method, which handles the actual API requests and response/error handling.
+
+<div class="note"><strong>Note:</strong>
+  Ledgers may support different operations for each resource type.
+</div>
+
+## 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::Ledgers::Contract
+  params do
+    required(:foo).filled(:string)
+  end
+end
+
+# A valid case
+custom_resource = CustomResource.new(foo: 'asdf')
+op = operation_class.new(
+  client: client,
+  resource: resource,
+  validation_contract: CustomContract
+)
+op.valid? # => true
+
+# An invalid case
+custom_resource = CustomResource.new(foo: nil)
+operation_class.new(
+  client: client,
+  resource: resource,
+  validation_contract: CustomContract
+)
+op.valid? # => false
+
+```

data/documentation/site/guides/architecture/resources.md

@@ -0,0 +1,40 @@
+---
+title: Resources
+weight: 2
+layout: guides
+---
+
+## Overview
+
+Resources are named ruby objects (e.g. `Customer`, `Payment`, etc.) with strict attributes (e.g. `name`, `amount`, etc.).  LedgerSync provides resources specific to each ledger.  While it is possible to create your own resources (see Customization for more details), this section refers to provided ledger-specific resources.
+
+The library strives to make each resource and attribute name match the ledger API.  This naming convention will help you more readily match ledger documentation to LedgerSync resources.
+
+Every resource, regardless of ledger, implements a `ledger_id` and `external_id` attribute.  The `ledger_id` is the ID given by the ledger, while the `external_id` is your internal ID for the resource.
+
+## How to use
+
+Resources are primary used as the inputs and outputs of operations and searchers.  A resource is passed to an operation along with a client.  Once the operation is successfully performed, a duplicated and updated resource is returned.
+
+Resources have two layers of validation:
+
+1. The Resource
+2. Operations
+
+When instantiating a resource, validations are performed.  These validations include class checks and, if necessary, value checks (e.g. enums).  When performing an operation, validations are performed based on what attributes are required for the operation to be successful.  For example, the `ledger_id` should be `nil` on `create`, but it should be present on `update`.
+
+## Available resources
+
+You can see all resources available for a given ledger by calling `resources` on the ledger's `Client` like so:
+
+`LedgerSync::Ledgers::QuickBooksOnline::Client.resources`
+
+This returns a hash of resource types to classes, where the resource types are unique (e.g. `customer`, `vendor`, etc.).
+
+You can see all resources available in LedgerSync by calling `LedgerSync.resources`.  This returns an array (note: not a hash as multiple ledgers have the same types) of resource classes that have been created inheriting the `LedgerSync::Resource` class.
+
+## Resource Attributes
+
+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 `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 `Customer.references`.

data/documentation/site/guides/architecture/results.md

@@ -0,0 +1,6 @@
+---
+title: Results
+weight: 6
+layout: guides
+---
+

data/documentation/site/guides/architecture/searchers.md

@@ -0,0 +1,28 @@
+---
+title: Operations
+weight: 5
+layout: guides
+---
+
+Searchers are used to search objects in the ledger.  A searcher takes an `client`, `query` string and optional `pagination` hash.  For example, to search customer's by name:
+
+```ruby
+searcher = LedgerSync::Ledgers::QuickBooksOnline::Customer::Searcher.new(
+  client: client # 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
+
+# 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
+```

data/documentation/site/guides/architecture/serialization.md

@@ -0,0 +1,59 @@
+---
+title: Serialization
+weight: 3
+layout: guides
+---
+
+## Overview
+
+LedgerSync leverages serialization and deserialization to convert resources into the necessary hash formats the ledger expects.  Generally, each resource will have 1 serializer and 1 deserializer.
+
+## Serializers
+
+Serializers take a `Resource` and output a hash.  For example:
+
+```ruby
+customer = LedgerSync::Ledgers::NetSuite::Customer.new(
+  companyName: 'Test Company',
+  external_id: 'ext_123'
+)
+serializer = LedgerSync::Ledgers::NetSuite::Customer::Serializer.new
+serializer.serialize(resource: customer)
+# Sample output:
+# {
+#   "companyName" => "Test Company",
+#   "externalId" => "ext_123",
+#   "email" => nil,
+#   "phone" => nil,
+#   "firstName" => nil,
+#   "lastName" => nil,
+#   "subsidiary" => nil
+# }
+end
+```
+
+## Deserializers
+
+Deserializers take a hash and output a `Resource`.  For example:
+
+```ruby
+h = {
+  "companyName" => "Test Company",
+  "externalId" => "ext_123",
+  "email" => nil,
+  "id" => "987654321",
+  "phone" => nil,
+  "firstName" => nil,
+  "lastName" => nil,
+  "subsidiary" => nil
+}
+
+deserializer = LedgerSync::Ledgers::NetSuite::Customer::Deserializer.new
+customer = deserializer.deserialize(hash: h, resource: LedgerSync::Ledgers::NetSuite::Customer.new)
+customer.ledger_id # => "987654321"
+customer.companyName # => "Test Company"
+```
+
+## How to use
+
+Serializers and deserializers are automatically inferred by each operation based on the naming convention.  It is possible to create your own serializers.  Please see [Customization](/guides/customization) for more.

data/documentation/site/guides/community/index.md

@@ -0,0 +1,8 @@
+---
+title: Where To Get Support
+excerpt: >-
+  Connect with the maintainers, contributers, and developers using LedgerSync.
+layout: guides
+---
+
+{% include getting_help.md page=page site=site %}

data/documentation/site/guides/contribute/console.md

@@ -0,0 +1,6 @@
+---
+title: Console
+layout: guides
+---
+
+Run `bundle console` to start and interactive console with the library already loaded. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/documentation/site/guides/contribute/deployment.md

@@ -0,0 +1,17 @@
+---
+title: Deployment
+layout: guides
+---
+
+<div class="note"><strong>Note:</strong>
+Only contributors can deploy new versions of the gem to RubyGems.org.
+</div>
+
+To deploy a new version of the gem to RubyGems, you can use the `release.sh` script in the root.  The script takes advantage of [the bump gem](https://github.com/gregorym/bump).  So you may call the script using any of the following:
+
+```bash
+# Version Format: MAJOR.MINOR.PATCH
+./release.sh patch # to bump X in 1.1.X
+./release.sh minor # to bump X in 1.X.1
+./release.sh major # to bump X in X.1.1
+```

data/documentation/site/guides/contribute/documentation.md

@@ -0,0 +1,37 @@
+---
+title: Documentation
+excerpt: >-
+  Learn how to document and update the documentation site.
+layout: guides
+---
+
+## Overview
+
+Our documentation is a static website hosted on Github pages.  The docs are a mix of static and dynamically-generated
+content.  The final static site is generated using Jekyll.
+
+## Install Jekyll
+
+To run or generate the docs site locally, you need to install Jekyll:
+
+```
+gem install jekyll bundler
+```
+
+## Run Jekyll
+
+To run Jekyll locally to view the site, run the following from the root directory:
+
+```
+cd docs/site
+bundle exec jekyll serve
+```
+
+## Generate dynamic pages
+
+Some of the documentation is generated based on the code of LedgerSync (e.g. available operations, resources, etc.). To
+generate these pages, run the following from the root directory:
+
+```
+ruby docs/generate.rb
+```

data/documentation/site/guides/contribute/index.md

@@ -0,0 +1,18 @@
+---
+title: Contribute
+excerpt: >-
+  Help expand LedgerSync coverage.
+layout: guides
+---
+
+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.
+
+## 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).
+
+## Installing the gem
+
+After checking out the repo, run `bin/setup` to install dependencies.
+
+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)

data/documentation/site/guides/contribute/qa.md

@@ -0,0 +1,16 @@
+---
+title: QA
+layout: guides
+---
+
+**BE SURE TO USE A TEST ENVIRONMENT ON YOUR LEDGER.**
+
+To fully test the library against the actual ledgers, you can run `bin/qa` which will run all tests in the `qa/` directory.  QA Tests are written in RSpec.  Unlike tests in the `spec/` directory, QA tests allow external HTTP requests.
+
+As these interact with real ledgers, you will need to provide secrets.  You can do so in a `.env` file in the root directory.  Copy the `.env.template` file to get started.
+
+**WARNINGS:**
+
+- **BE SURE TO USE A TEST ENVIRONMENT ON YOUR LEDGER.**
+- **NEVER CHECK IN YOUR SECRETS (e.g. the `.env` file).**
+- Because these tests actually create and modify resources, they attempt to do "cleanup" by deleting any newly created resources.  This process could fail, and you may need to delete these resources manually.

data/documentation/site/guides/contribute/testing.md

@@ -0,0 +1,6 @@
+---
+title: Testing
+layout: guides
+---
+
+Run `bundle exec rspec` to run all unit, feature, and integration tests.  Unlike [QA Tests](/guides/contribute/qa), all external HTTP requests and responses are stubbed.

data/documentation/site/guides/customization/custom_resources.md

@@ -0,0 +1,50 @@
+---
+title: Custom Resources
+layout: guides
+weight: 2
+---
+
+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::Ledgers::QuickBooksOnline::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|
+  customer_class = Class.new(LedgerSync::Ledgers::QuickBooksOnline::Customer)
+  attributes.each do |name, type|
+    customer_class.attribute name, type: type
+  end
+  customer_class
+end
+
+customer_class_1, customer_class_2 = custom_customer_classes
+
+# First Custom Customer Class
+customer_class_1.resource_attributes.include?(:foo) # => true
+customer_class_1.resource_attributes[:foo].type # => #<LedgerSync::Type::String:0x00007fe04e9529b0 @precision=nil, @scale=nil, @limit=nil>
+customer_class_1.resource_attributes.include?(:bar) # => false
+
+# Second Custom Customer Class
+customer_class_2.resource_attributes.include?(:foo) # => true
+customer_class_2.resource_attributes[:foo].type # => #<LedgerSync::Type::Integer:0x00007fe04e2c7898 @precision=nil, @scale=nil, @limit=nil, @range=-2147483648...2147483648>
+customer_class_2.resource_attributes.include?(:bar) # => true
+customer_class_2.resource_attributes[:bar].type # => #<LedgerSync::Type::Boolean:0x00007fe04e2e4f10 @precision=nil, @scale=nil, @limit=nil>
+```
+
+You can now use these custom resources in operations that use or require custom attributes.

data/documentation/site/guides/customization/custom_serializers.md

@@ -0,0 +1,47 @@
+---
+title: Custom Serializers
+layout: guides
+weight: 2
+---
+
+When you need to pass new attributes to/from a ledger, you may to to create custom serializers and deserializers.
+
+For example, given the following:
+
+- `CustomCustomer` is a custom resource that inherits from `LedgerSync::Ledgers::NetSuite::Customer` and defines a custom attribute string named `foo`
+- the attribute `foo` is used in both the request and response bodies
+- `client` defines a valid instance of the NetSuite client
+
+
+```ruby
+class CustomSerializer < LedgerSync::Ledgers::NetSuite::Customer::Serializer
+  attribute :foo
+end
+
+class CustomDeserializer < LedgerSync::Ledgers::NetSuite::Customer::Deserializer
+  attribute :foo
+end
+
+# Serializing
+custom_resource = CustomCustomer.new(foo: 'asdf') # See above under Resources -> Custom Attributes
+serializer = CustomSerializer.new(resource: custom_resource)
+serializer.serialize # => {..., "foo"=>"asdf",...}
+
+# Deserializing
+deserialized_resource = serializer.deserialize(hash: { foo: 'qwerty' }, resource: CustomCustomer.new)
+deserialized_resource.foo # => 'qwerty'
+custom_resource.foo # => 'asdf'
+
+op = LedgerSync::Ledgers::NetSuite::Customer::Operations::Create.new(
+  client: client,
+  deserializer: CustomSerializer.new,
+  serializer: CustomSerializer.new,
+  resource: custom_resource
+)
+```
+
+Note that in the above example, we extend an existing customer serializer in the NetSuite ledger.  In most cases, serializers have the following inheritance pattern: `LedgerSync::Ledgers::[ADAPTOR]::[RESOURCE]::Serializer <  LedgerSync::Ledgers::[ADAPTOR]::Serializer <  LedgerSync::Serializer`.
+
+So in this example, it would be `LedgerSync::Ledgers::NetSuite::Customer::Serializer <  LedgerSync::Ledgers::NetSuite::Serializer <  LedgerSync::Serializer`.  The more specific the serializer, the more helper methods are available that are ledger and/or resource specific.
+
+Similarly, deserializers follow the same pattern.