ledger_sync 1.3.3 → 1.4.2

data/documentation/site/overview.md

@@ -0,0 +1,21 @@
+---
+title: Overview
+sections:
+  - section_id: hero
+    type: section_hero
+    title: Overview
+    image: images/5.jpg
+    content: An optional subtitle
+  - section_id: guides-overview
+    type: section_guides
+    col_number: three
+  - section_id: cta
+    type: section_cta
+    title: The Title of The Call to Action Block
+    subtitle: This is an optional description for the call to action block.
+    actions:
+      - label: Get Started
+        url: /guides/getting-started/index.html
+        type: primary
+layout: advanced
+---

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

@@ -0,0 +1,33 @@
+---
+title: Clients
+weight: 1
+layout: reference
+---
+
+## 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.
+
+## 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/reference/architecture/index.md

@@ -0,0 +1,14 @@
+---
+title: Architecture
+excerpt: Understand the high-level architecture of LedgerSync.
+layout: reference
+---
+
+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/reference/architecture/operations.md

@@ -0,0 +1,6 @@
+---
+title: Operations
+weight: 4
+layout: reference
+---
+

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

@@ -0,0 +1,38 @@
+---
+title: Resources
+weight: 2
+layout: reference
+---
+
+## 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.
+
+## 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/reference/architecture/results.md

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

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

@@ -0,0 +1,6 @@
+---
+title: Operations
+weight: 5
+layout: reference
+---
+

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

@@ -0,0 +1,6 @@
+---
+title: Serialization
+weight: 3
+layout: reference
+---
+

data/documentation/site/reference/index.md

@@ -0,0 +1,6 @@
+---
+title: Reference
+layout: reference
+---
+
+Select a ledger from the dropdown in the navigation.

data/documentation/site/reference/netsuite/authentication/_token_based_authentication.md

@@ -0,0 +1,99 @@
+## Overview
+
+In order to authenticate to NetSuite, you need the following:
+
+- `account_id`
+- `consumer_key`
+- `consumer_secret`
+- `token_id`
+- `token_secret`
+
+We will walk through how to get each value in the following sections.
+
+<div class="note"><strong>Note:</strong>
+You need to have sufficient permissions to set up your account for API authentication.
+</div>
+
+## Prerequisites
+
+### REST Web Services feature
+
+Enable the feature at Setup > Company > Setup Tasks > Enable Features, in the SuiteTalk (Web Services) section, on the SuiteCloud subtab. To use the feature, you must accept the SuiteCloud Terms of Service.
+
+### SuiteAnalytics Workbook feature
+
+Enable the feature at Setup > Company > Setup Tasks > Enable Features, on the Analytics subtab.
+
+### Permissions
+
+You will require the following permissions:
+
+- REST Web Services
+- Log in using Access Tokens
+- SuiteAnalytics Workbook
+
+Your permissions vary based on which role you are assigned.  You can edit roles in Setup > Users/Roles > User Management > Manage Roles.  Ensure your user is assigned a role with the aforementioned permissions in order to complete the setup.
+
+<div class="note"><strong>Note:</strong>
+<p>
+  There are two different sets of permissions you will need:
+</p>
+<p>
+  <ul>
+    <li>The permissions mentioned above are to <strong>set up</strong> your integration.</li>
+    <li>Later when creating a token, you will need to assign a user with a role that has the necessary permissions to <strong>access records</strong> (e.g. payments, invoices, bills, etc.)</li>
+  </ul>
+</p>
+
+<p>
+These can be the same or different roles.  They can be assigned to one or many users.
+</p>
+</div>
+
+## Account ID
+
+The `account_id` can be found in the URL when you are logged into the NetSuite dashboard in your browser.  It will look
+something like the following:
+
+```
+https://<account_id>.app.netsuite.com/app/center/card.nl?sc=-29&whence=
+```
+
+Example:
+
+```
+https://123456.app.netsuite.com/app/center/card.nl?sc=-29&whence=
+```
+
+The Account ID precedes `.app.netsuite.com`, which in this case is `123456`.  Note that your ID may include `-sb1`
+(representing "Sandbox 1").  Be sure to include the entire ID as it appears in the URL, including any letters, numbers,
+and hyphens.
+
+## Consumer Keys
+
+The consumer keys are retrieved when you [create an Integration record](https://system.netsuite.com/app/help/helpcenter.nl?fid=bridgehead_4249032125.html&whence=).  You can view [the NetSuite documentation](https://system.netsuite.com/app/help/helpcenter.nl?fid=bridgehead_4249032125.html&whence=) for the official documentation.
+
+At the last step of creating an Integration record, save the consumer key and consumer secret.  They will not be shown again once you navigate away from the page.
+
+## Token
+
+To obtain your `token_key` and `token_secret`, you will need to [create a Token](https://system.netsuite.com/app/help/helpcenter.nl?fid=bridgehead_4254081947.html).  View [the NetSuite documentation](https://system.netsuite.com/app/help/helpcenter.nl?fid=bridgehead_4254081947.html) for the official documentation.
+
+You will use the integration record you created along with your user (or the user who has the necessary permissions to access records).
+
+At the last step, save the token key and token secret.
+
+## Conclusion
+
+Now with these values, you can successfully authenticate to NetSuite.  Simply pass the values into the client:
+
+{% highlight ruby linenos %}
+client = LedgerSync::Ledgers::QuickBooksOnline::Client.new(
+  account_id: account_id,
+  consumer_key: consumer_key,
+  consumer_secret: consumer_secret,
+  token_id: token_id,
+  token_secret: token_secret
+)
+{% endhighlight %}
+

data/documentation/site/reference/netsuite/authentication/index.md

@@ -0,0 +1,15 @@
+---
+title: Authentication
+layout: reference_netsuite
+ledger: netsuite
+---
+
+For the REST API, NetSuite offers two types of authentication:
+
+- Token Based Authentication (TBA)
+- Oauth 2.0
+
+This client currently uses TBA.  While Oauth 2.0 may be available in the future, TBA was chosen for the following reasons:
+
+1. The SOAP API only supports TBA.
+2. NetSuite users will still need to go through a manual setup (e.g. Integration record and Role) regardless of the method.

data/documentation/site/reference/netsuite/authentication/token_based_authentication.md

@@ -0,0 +1,6 @@
+---
+title: Token Based Authentication
+layout: reference_netsuite
+---
+
+{% include reference/netsuite/authentication/_token_based_authentication.md %}

data/documentation/site/reference/netsuite/index.md

@@ -0,0 +1,25 @@
+---
+title: NetSuite
+layout: reference_netsuite
+ledger: netsuite
+---
+
+### Resource Metadata and Schemas
+
+Due to NetSuites granular user permissions and custom attributes, resources and methods for those resources can vary from one user (a.k.a. token) to another.  Because of this variance, there are some helper classes that allow you to retrieve NetSuite records, allowed methods, attributes/parameters, etc.
+
+To retrieve the metadata for a record:
+
+```ruby
+metadata = LedgerSync::Ledgers::NetSuite::Record::Metadata.new(
+  client: netsuite_client, # Assuming this is previous defined
+  record: :customer
+)
+
+puts metadata.http_methods # Returns a list of LedgerSync::Ledgers::NetSuite::Record::HTTPMethod objects
+puts metadata.properties # Returns a list of LedgerSync::Ledgers::NetSuite::Record::Property objects
+```
+
+### Reference
+
+- [NetSuite REST API Documentation](https://docs.oracle.com/cloud/latest/netsuitecs_gs/NSTRW/NSTRW.pdf)

data/documentation/site/reference/netsuite/resources/account.md

@@ -0,0 +1,38 @@
+---
+title: account
+weight: 1
+layout: reference_netsuite
+---
+
+## LedgerSync::Ledgers::NetSuite::Account
+
+## Attributes
+
+| Name | Type |
+| ---- | ---- |
+| external_id | LedgerSync::Type::ID |
+| ledger_id | LedgerSync::Type::ID |
+| name | LedgerSync::Type::String |
+| classification | LedgerSync::Type::String |
+| account_type | LedgerSync::Type::StringFromSet |
+| account_sub_type | LedgerSync::Type::String |
+| number | LedgerSync::Type::String |
+| description | LedgerSync::Type::String |
+| active | LedgerSync::Type::Boolean |
+| currency | LedgerSync::Type::ReferenceOne |
+
+
+## Operations
+
+### LedgerSync::Ledgers::NetSuite::Account::Operations::Find
+
+#### Resource Validations
+
+| Name | Type |
+| ---- | ---- |
+### LedgerSync::Ledgers::NetSuite::Account::Operations::Create
+
+#### Resource Validations
+
+| Name | Type |
+| ---- | ---- |

data/documentation/site/reference/netsuite/resources/check.md

@@ -0,0 +1,49 @@
+---
+title: check
+weight: 2
+layout: reference_netsuite
+---
+
+## LedgerSync::Ledgers::NetSuite::Check
+
+## Attributes
+
+| Name | Type |
+| ---- | ---- |
+| external_id | LedgerSync::Type::ID |
+| ledger_id | LedgerSync::Type::ID |
+| memo | LedgerSync::Type::String |
+| trandate | LedgerSync::Type::String |
+| account | LedgerSync::Type::ReferenceOne |
+| department | LedgerSync::Type::ReferenceOne |
+| entity | LedgerSync::Type::ReferenceOne |
+| currency | LedgerSync::Type::ReferenceOne |
+| line_items | LedgerSync::Type::ReferenceMany |
+
+
+## Operations
+
+### LedgerSync::Ledgers::NetSuite::Check::Operations::Find
+
+#### Resource Validations
+
+| Name | Type |
+| ---- | ---- |
+### LedgerSync::Ledgers::NetSuite::Check::Operations::Create
+
+#### Resource Validations
+
+| Name | Type |
+| ---- | ---- |
+### LedgerSync::Ledgers::NetSuite::Check::Operations::Update
+
+#### Resource Validations
+
+| Name | Type |
+| ---- | ---- |
+### LedgerSync::Ledgers::NetSuite::Check::Operations::Delete
+
+#### Resource Validations
+
+| Name | Type |
+| ---- | ---- |

data/documentation/site/reference/netsuite/resources/check_line_item.md

@@ -0,0 +1,23 @@
+---
+title: check_line_item
+weight: 3
+layout: reference_netsuite
+---
+
+## LedgerSync::Ledgers::NetSuite::CheckLineItem
+
+## Attributes
+
+| Name | Type |
+| ---- | ---- |
+| external_id | LedgerSync::Type::ID |
+| ledger_id | LedgerSync::Type::ID |
+| account | LedgerSync::Type::ReferenceOne |
+| ledger_class | LedgerSync::Type::ReferenceOne |
+| department | LedgerSync::Type::ReferenceOne |
+| amount | LedgerSync::Type::Float |
+| memo | LedgerSync::Type::String |
+
+
+## Operations
+

data/documentation/site/reference/netsuite/resources/currency.md

@@ -0,0 +1,45 @@
+---
+title: currency
+weight: 4
+layout: reference_netsuite
+---
+
+## LedgerSync::Ledgers::NetSuite::Currency
+
+## Attributes
+
+| Name | Type |
+| ---- | ---- |
+| external_id | LedgerSync::Type::ID |
+| ledger_id | LedgerSync::Type::ID |
+| exchange_rate | LedgerSync::Type::Float |
+| name | LedgerSync::Type::String |
+| symbol | LedgerSync::Type::String |
+
+
+## Operations
+
+### LedgerSync::Ledgers::NetSuite::Currency::Operations::Find
+
+#### Resource Validations
+
+| Name | Type |
+| ---- | ---- |
+### LedgerSync::Ledgers::NetSuite::Currency::Operations::Create
+
+#### Resource Validations
+
+| Name | Type |
+| ---- | ---- |
+### LedgerSync::Ledgers::NetSuite::Currency::Operations::Update
+
+#### Resource Validations
+
+| Name | Type |
+| ---- | ---- |
+### LedgerSync::Ledgers::NetSuite::Currency::Operations::Delete
+
+#### Resource Validations
+
+| Name | Type |
+| ---- | ---- |