ledger_sync-quickbooks_online 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4b5e19720b4663f9e5ffa823f130bb7c45e4a0494b13cd6d021d53e1c9c4c8f
-  data.tar.gz: a17b5989f741070a84cd18c01b0e94e605cfb9ebe00cf0406bf0a23a52ec4bae
+  metadata.gz: 14034a8009fa439eaadc08eba6148a340cce02849d85ffe1d2f273c95b1a8831
+  data.tar.gz: 34fce60e7b7f9eee203365815d717d410a945f2b532ac2ea81370067bf2ef00e
 SHA512:
-  metadata.gz: ff2c96e34e1b6adb51af4aff4565735acdb8a50ac6b3a458ad5497b866506eae2b1986fdc0da5ff3daca89022fef610e8d6386300e189ad13bd797afdafdf891
-  data.tar.gz: b819e78fb472bb129c7ae51afec95aa2e4b46cbfec100bb26ce0f686f0c084714906c85ff52ad5d6fbbfab7dda104c5d957e25ff49c0679d4b107241dbf995e3
+  metadata.gz: 6d10a6ef31062c9ec3c2e4a70fc3563e9d3defd18537b1b981d9ab8a05c5ced276330bd43d0d9d1b2b0deecce1ce3afa466dc4c6e96ac9c71ef8f0aa34f3beb9
+  data.tar.gz: 9531d554f92faba1580a288a5978d590d3c8392ebc3b5233c6f05068c236892b43cc1a45da65c2842bbb64e69ddd543f5b1bbae88c16ba246af69c6d77c18690

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ledger_sync-quickbooks_online (0.3.0)
+    ledger_sync-quickbooks_online (0.3.1)
       dotenv
       ledger_sync (>= 2.0.2)
       oauth2
@@ -44,10 +44,10 @@ GEM
     dry-container (0.8.0)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 0.1, >= 0.1.3)
-    dry-core (0.6.0)
+    dry-core (0.7.0)
       concurrent-ruby (~> 1.0)
     dry-equalizer (0.3.0)
-    dry-inflector (0.2.0)
+    dry-inflector (0.2.1)
     dry-initializer (3.0.4)
     dry-logic (1.2.0)
       concurrent-ruby (~> 1.0)
@@ -75,12 +75,14 @@ GEM
       dry-schema (~> 1.5, >= 1.5.2)
     factory_bot (6.1.0)
       activesupport (>= 5.0.0)
-    faraday (1.4.2)
+    faraday (1.5.0)
       faraday-em_http (~> 1.0)
       faraday-em_synchrony (~> 1.0)
       faraday-excon (~> 1.1)
+      faraday-httpclient (~> 1.0.1)
       faraday-net_http (~> 1.0)
       faraday-net_http_persistent (~> 1.1)
+      faraday-patron (~> 1.0)
       multipart-post (>= 1.2, < 3)
       ruby2_keywords (>= 0.0.4)
     faraday-detailed_logger (2.3.0)
@@ -88,8 +90,10 @@ GEM
     faraday-em_http (1.0.0)
     faraday-em_synchrony (1.0.0)
     faraday-excon (1.1.0)
+    faraday-httpclient (1.0.1)
     faraday-net_http (1.0.1)
     faraday-net_http_persistent (1.1.0)
+    faraday-patron (1.0.0)
     faraday_middleware (1.0.0)
       faraday (~> 1.0)
     fingerprintable (1.2.1)
@@ -115,11 +119,13 @@ GEM
       rack (~> 2.2.3)
       resonad
       simply_serializable (>= 1.5.1)
+    mini_portile2 (2.5.3)
     minitest (5.14.4)
     multi_json (1.15.0)
     multi_xml (0.6.0)
     multipart-post (2.1.1)
-    nokogiri (1.11.7-x86_64-darwin)
+    nokogiri (1.11.7)
+      mini_portile2 (~> 2.5.0)
       racc (~> 1.4)
     oauth2 (1.4.7)
       faraday (>= 0.8, < 2.0)
@@ -175,6 +181,7 @@ GEM
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
+    simplecov-lcov (0.8.0)
     simply_serializable (1.5.1)
       fingerprintable (>= 1.2.1)
     sync (0.5.0)
@@ -209,6 +216,7 @@ DEPENDENCIES
   rake (~> 13.0)
   rspec (~> 3.2)
   rubocop
+  simplecov-lcov
   vcr
   webmock
 

data/README.md

@@ -1,19 +1,217 @@
-# LedgerSync::QuickBooksOnline
+<a name="ledger-sync--quick-books-online" />
+
+# LedgerSync for QuickBooksOnline
 
 [![Build Status](https://travis-ci.org/LedgerSync/ledger_sync-quickbooks_online.svg?branch=master)](https://travis-ci.org/LedgerSync/ledger_sync-quickbooks_online)
 [![Gem Version](https://badge.fury.io/rb/ledger_sync-quickbooks_online.svg)](https://badge.fury.io/rb/ledger_sync-quickbooks_online)
 [![Coverage Status](https://coveralls.io/repos/github/LedgerSync/ledger_sync-quickbooks_online/badge.svg?branch=master)](https://coveralls.io/github/LedgerSync/ledger_sync-quickbooks_online?branch=master)
 
-[ledgersync.dev](www.ledgersync.dev)
 
-## Usage
+<a name="ledger-sync--quick-books-online--join-the-conversation" />
+
+## Join the Conversation
+
+[Click here](https://join.slack.com/t/ledger-sync/shared_invite/zt-e5nbl8qc-eOA~5k7bg3p16_l3J7OS~Q) to join our public Slack group.
+
+
+<a name="architecture" />
+
+## Architecture
+
+This gem is built on top of the core [LedgerSync](https://github.com/LedgerSync/ledger_sync) gem. If you are unfamiliar with the LedgerSync architecture, it is recommended to first read through the [LedgerSync documentation](https://github.com/LedgerSync/ledger_sync).
+
+<a name="getting-started" />
+
+## Installation
+
+<a name="getting-started--installation--gemfile" />
+
+### Gemfile
+
+Add this line to your application’s Gemfile:
+
+```
+gem 'ledger_sync-quickbooks_online'
+```
+
+And then execute:
+```
+bundle
+```
+
+<a name="getting-started--installation--directly" />
+
+### Directly
+
+Or install it yourself as:
+
+```
+gem install ledger_sync-quickbooks_online
+```
+
+<a name="getting-started--oauth" />
+
+## OAuth
+
+QuickBooks Online utilizes OAuth 2.0, which requires frequent refreshing of the access and refresh token. The client will handle this automatically, attempting a single token refresh on any single request authentication failure due to an expired access token.
+
+The `LedgerSync::QuickBooksOnline::Client` implements a `ledger_attributes_to_save` class method, which is an array of attributes that may change as the client is used (e.g. `access_token`).  You can also call the instance method `ledger_attributes_to_save` which will be a hash of these current values. It is a best practice to always store these attributes
+if you are saving access tokens in your database.
+
+Should you fail to save the current `refresh_token`, you will have to ask your user to reconnect to QuickBooks Online again.
+
+<a name="getting-started--oauth--retrieveAccessToken" />
+
+### Retrieve Access Token
+
+The library contains a lightweight script that is helpful in retrieving and refreshing access tokens. It is particularly useful during development, when you do not have an application to handle the redirects and OAuth code exchange. To use, do the following:
+
+1. Create a `.env.local` file in the library root.
+2. Add values for `QUICKBOOKS_ONLINE_CLIENT_ID` and `QUICKBOOKS_ONLINE_CLIENT_SECRET` (you can copy `.env.test` as a template).
+3. Ensure your developer application in [the QuickBooks Online developer portal](https://developer.intuit.com) contains this redirect URI: `http://localhost:5678` (note: no trailing slash and port configurable with `PORT` environment variable)
+4. Run `ruby bin/quickbooks_online_oauth_server.rb` from the library root (note: it must run from the root in order to update `.env.local`).
+5. Visit the URL output in the terminal.
+6. Upon redirect back to `http://localhost:5678`, the new values will be printed to the console and saved back to your `.env.local`
+
+<a name="getting-started--oauth--ledger-helper-methods" />
+
+### Ledger Helper Methods
+
+The client also implements some helper methods for getting tokens.  For example, you can set up a client using the following:
+
+```ruby
+# Retrieve the following values from Intuit app settings
+client_id     = ENV['QUICKBOOKS_ONLINE_CLIENT_ID']
+client_secret = ENV['QUICKBOOKS_ONLINE_CLIENT_SECRET']
+redirect_uri  = 'http://localhost:3000'
+
+oauth_client = LedgerSync::QuickBooksOnline::OAuthClientHelper.new(
+  client_id: client_id,
+  client_secret: client_secret
+)
+
+puts oauth_client.authorization_url(redirect_uri: redirect_uri)
+
+# Visit on the output URL and authorize a company.
+# You will be redirected back to the redirect_uri.
+# Copy the full url from your browser:
+
+uri = 'https://localhost:3000/?code=FOO&state=BAR&realm_id=BAZ'
+
+client = LedgerSync::QuickBooksOnline::Client.new_from_oauth_client_uri(
+  oauth_client: oauth_client,
+  uri: uri
+)
+
+# You can test that the auth works:
+
+client.refresh!
+```
+
+**Note: If you have a `.env.local` file storing your secrets, the client will automatically update the variables and record previous values whenever values change*
+
+<a name="client" />
+
+# Client
+
+You can instantiate a client like so:
+
+```ruby
+client = LedgerSync::Ledgers::QuickBooksOnline::Client.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
+  update_dotenv: true # Optional: defaults to true
+)
+```
+
+## `update_dotenv`
+
+When `update_dotenv` is `true`, the library will automatically update your `.env.local` (or otherwise configured `.env` file).
+
+When `update_dotenv` is `false`, you will need to manually save the refreshed attributes after each operation call. The `result` is the output of calling `operation.perform` and gives you access to the updated `client`. You can access the new values by doing the following:
+
+```ruby
+result.operation.client.ledger_attributes_to_save.each do |key, value|
+  # save values
+end
+```
+
+<a name="resources" />
+
+# Resources
+
+To see all the available resources, you can call `LedgerSync::QuickBooksOnline::Client.resources`, which will give you a hash of keys and resource classes.
+
+## Resource Attributes
+
+
+To see all the available attributes of a resource you can call the `resource_attributes` class method. For example, you can call `LedgerSync::QuickBooksOnline::Customer.resource_attributes`, which will return a `LedgerSync::ResourceAttributeSet`. This object allows you to see the attributes and the type of each attribute. For example, you can see the attribute `DisplayName` and its type by typing the following:
+
+```bash
+> LedgerSync::QuickBooksOnline::Customer.resource_attributes.attributes[:DisplayName]
+=> #<LedgerSync::ResourceAttribute:0x00007fef3dafe568 @name=:DisplayName, @resource_class=LedgerSync::QuickBooksOnline::Customer, @type=#<LedgerSync::Type::String:0x00007fef3dafe540 @true="t", @false="f", @precision=nil, @scale=nil, @limit=nil>, @value=nil>
+```
+## Resource Operations
+
+
+To see all the available operations for a given resource you can call the `operations` class method. For example, you can call `LedgerSync::QuickBooksOnline::Customer.operations`, which will return a hash of keys mapped to operation classes. For example, you can try the following:
+
+```bash
+> LedgerSync::QuickBooksOnline::Customer.operations
+=> {:find=>LedgerSync::QuickBooksOnline::Customer::Operations::Find, :create=>LedgerSync::QuickBooksOnline::Customer::Operations::Create, :update=>LedgerSync::QuickBooksOnline::Customer::Operations::Update}
+```
+
+<a name="examples" />
+
+# Examples
+
+## Create a Customer
+
+```ruby
+client = LedgerSync::Ledgers::QuickBooksOnline::Client.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
+)
+
+resource = LedgerSync::Ledgers::QuickBooksOnline::Customer.new(
+  DisplayName: 'Sample Customer',
+  external_id: customer_external_id # A unique ID from your platform
+)
+
+operation = LedgerSync::Ledgers::QuickBooksOnline::Customer::Operations::Create.new(
+  client: client,
+  resource: resource
+)
+
+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
+
+```
+
+<a name="errors" />
+
+# Errors
+
+While LedgerSync tries to catch and translate errors, not all errors will be caught (e.g. new errors from the QuickBooks Online API).  In these cases, you can rescue a generic `LedgerSync::OperationError` and determine what to do based on the response body.
+
+[QuickBooks Online Error Documentation](https://developer.intuit.com/app/developer/qbo/docs/develop/troubleshooting/error-codes)
+
+
+
+<a name="ledger-sync--quick-books-online--license" />
 
-This template ledger enables you to easily create your own ledger for public or private use. Although this is not an
-exhaustive list, a good place to start assuming your ledger name is `NewLedger`:
+## License
 
-1. Find and replace all `QUICK_BOOKS_ONLINE` with `NEW_LEDGER`
-2. Find and replace all `QuickBooksOnline` with `NewLedger`
-3. Find and replace all `quickbooks_online` with `new_ledger`
-4. Find and replace all `QuickBooks Online` with `New Ledger`
-5. Find and replace all `quickbooks_online` directories and files with `new_ledger`
-6. Remove `SampleResource` example files.
+This gem and all code contained in the repository is licensed under the same license as the core [LedgerSync](https://github.com/LedgerSync/ledger_sync) license. You can view all license details in the [LedgerSync](https://github.com/LedgerSync/ledger_sync) repo.

data/ledger_sync-quickbooks_online.gemspec

@@ -37,6 +37,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency('rake', '~> 13.0')
   spec.add_development_dependency('rspec', '~> 3.2')
   spec.add_development_dependency('rubocop', '>= 0')
+  spec.add_development_dependency('simplecov-lcov')
   spec.add_development_dependency('vcr', '>= 0')
   spec.add_development_dependency('webmock', '>= 0')
   spec.add_runtime_dependency('dotenv')

data/lib/ledger_sync/quickbooks_online/client.rb

@@ -34,8 +34,8 @@ module LedgerSync
         client_secret:,
         realm_id:,
         refresh_token:,
-        expires_at:,
-        refresh_token_expires_at:,
+        expires_at: nil,
+        refresh_token_expires_at: nil,
         test: false,
         update_dotenv: true
       )

data/lib/ledger_sync/quickbooks_online/version.rb

@@ -3,7 +3,7 @@
 # :nocov:
 module LedgerSync
   module QuickBooksOnline
-    VERSION = '0.3.0'
+    VERSION = '0.3.1'
 
     def self.version(args = {})
       pre = args.fetch(:pre, false)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ledger_sync-quickbooks_online
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Modern Treasury
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-06-12 00:00:00.000000000 Z
+date: 2021-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -164,6 +164,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
@@ -434,7 +448,7 @@ files:
 homepage: https://www.ledgersync.dev
 licenses: []
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -449,8 +463,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.0.3
+signing_key:
 specification_version: 4
 summary: Sync common objects to accounting software.
 test_files: []