effective_qb_online 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 41c564325389352ce139af8d840c39d3f5ffaa132efd7f8bb72c5d7fe28927af
+  data.tar.gz: 505c8393cf0e7a06b6a687ccebda7c510f9590a248cc111e4c524027cb9b8163
+SHA512:
+  metadata.gz: 06fd5e50780c61176aaf4df670888855cd7590a5fb9f949d2a5d50686e2c077e8719c1a454327d2c6f82721ecf596fd0ed2f0c8d1ce4a056293d9f40c1bd11c5
+  data.tar.gz: da8ba5c9871f8988a4e2d74393779ebd9b0b4e97c5fa4b8d65304d264556cfe1d1d1078c4d0ec3d049d48d6232d416651054f52a8beb1a27450037cee52576fe

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Code and Effect Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,96 @@
+# Effective Quickbooks Online
+
+Create Quickbooks Online SalesReceipts for purchased effective orders.
+
+## Getting Started
+
+This requires Rails 6+ and Twitter Bootstrap 4 and just works with Devise.
+
+Please first install the [effective_datatables](https://github.com/code-and-effect/effective_datatables) gem.
+
+Please download and install the [Twitter Bootstrap4](http://getbootstrap.com)
+
+Add to your Gemfile:
+
+```ruby
+gem 'haml-rails' # or try using gem 'hamlit-rails'
+gem 'effective_qb_online'
+```
+
+Run the bundle command to install it:
+
+```console
+bundle install
+```
+
+Then run the generator:
+
+```ruby
+rails generate effective_qb_online:install
+```
+
+The generator will install an initializer which describes all configuration options and creates a database migration.
+
+If you want to tweak the table names, manually adjust both the configuration file and the migration now.
+
+Then migrate the database:
+
+```ruby
+rake db:migrate
+```
+
+```
+Add a link to the admin menu:
+
+```haml
+- if can? :admin, :effective_qb_online
+  = nav_link_to 'Quickbooks Online', effective_qb_online.admin_quickbooks_path
+```
+
+and visit `/admin/quickbooks`.
+
+## Authorization
+
+All authorization checks are handled via the effective_resources gem found in the `config/initializers/effective_resources.rb` file.
+
+## Permissions
+
+The permissions you actually want to define are as follows (using CanCan):
+
+```ruby
+if user.admin?
+  can :admin, :effective_qb_online
+
+  can(crud, Effective::QbRealm)
+  can(crud + [:skip, :sync], Effective::QbReceipt) { |receipt| !receipt.completed? }
+end
+```
+
+## Configuring Quickbooks Company
+
+This gem has only been tested with a Canadian Quickbooks Online store.
+
+It has GST, HST and Tax Exempt tax codes and rates set up ahead of time by Quickbooks.
+
+## License
+
+MIT License. Copyright [Code and Effect Inc.](http://www.codeandeffect.com/)
+
+## Testing
+
+There are tests, but the access token and refresh token doesn't work well.
+
+You must visit /admin/quickbooks and copy & paste the test credentials into ~/.env
+
+```ruby
+rails test
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Bonus points for test coverage
+6. Create new Pull Request

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/assets/config/effective_qb_online_manifest.js

@@ -0,0 +1,3 @@
+//= link_directory ../javascripts .js
+//= link_directory ../stylesheets .css
+//= link_tree ../images

data/app/assets/javascripts/effective_qb_online.js

@@ -0,0 +1 @@
+//= require_tree ./effective_qb_online

data/app/assets/stylesheets/effective_qb_online.scss

@@ -0,0 +1 @@
+@import 'effective_qb_online/base';

data/app/controllers/admin/qb_online_controller.rb

@@ -0,0 +1,20 @@
+module Admin
+  class QbOnlineController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+    before_action { EffectiveResources.authorize!(self, :admin, :effective_qb_online) }
+
+    include Effective::CrudController
+
+    page_title 'Quickbooks Online'
+
+    # /admin/quickbooks
+    def index
+      @api = EffectiveQbOnline.api
+
+      authorize! :index, Effective::QbRealm
+
+      render(@api.present? ? 'index' : 'instructions')
+    end
+
+  end
+end

data/app/controllers/admin/qb_realms_controller.rb

@@ -0,0 +1,11 @@
+module Admin
+  class QbRealmsController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+    before_action { EffectiveResources.authorize!(self, :admin, :effective_qb_online) }
+
+    include Effective::CrudController
+
+    on :save, redirect: -> { effective_qb_online.admin_quickbooks_path }
+
+  end
+end

data/app/controllers/admin/qb_receipts_controller.rb

@@ -0,0 +1,17 @@
+module Admin
+  class QbReceiptsController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+    before_action { EffectiveResources.authorize!(self, :admin, :effective_qb_online) }
+
+    include Effective::CrudController
+
+    on :skip, redirect: -> { effective_qb_online.admin_quickbooks_path }
+
+    on :sync, redirect: -> {
+      resource.completed? ? effective_qb_online.admin_quickbooks_path : :edit
+    }
+
+    submit :sync, 'Save and Sync'
+
+  end
+end

data/app/controllers/effective/qb_oauth_controller.rb

@@ -0,0 +1,52 @@
+# http://caaa.test:3000/quickbooks/oauth/authorize
+
+module Effective
+  class QbOauthController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+
+    # Any user that has priviledges with the Quickbooks Online company could authenticate
+    # But we assume this user also has admin priviledges on our site
+    # This should only be done once anyway
+    before_action { EffectiveResources.authorize!(self, :admin, :effective_qb_online) }
+
+    def authorize
+      grant_url = EffectiveQbOnline.oauth2_client.auth_code.authorize_url(
+        redirect_uri: redirect_uri,
+        response_type: 'code',
+        state: SecureRandom.hex(12),
+        scope: 'com.intuit.quickbooks.accounting'
+      )
+
+      redirect_to(grant_url)
+    end
+
+    # This matches the Quickbooks Redirect URI and we have to set it up ahead of time.
+    def callback
+      return unless params[:code].present? && params[:realmId].present? && params[:state].present?
+
+      token = EffectiveQbOnline.oauth2_client.auth_code.get_token(params[:code], redirect_uri: redirect_uri)
+      return unless token
+
+      realm = Effective::QbRealm.all.first_or_initialize
+
+      realm.update!(
+        realm_id: params[:realmId],
+        access_token: token.token,
+        refresh_token: token.refresh_token,
+        access_token_expires_at: Time.at(token.expires_at),
+        refresh_token_expires_at: (Time.at(token.expires_at) + 100.days)
+      )
+
+      flash[:success] = 'Successfully connected with Quickbooks Online'
+
+      redirect_to(effective_qb_online.admin_quickbooks_path)
+    end
+
+    private
+
+    def redirect_uri
+      effective_qb_online.quickbooks_oauth_callback_url
+    end
+
+  end
+end

data/app/datatables/admin/effective_qb_receipts_datatable.rb

@@ -0,0 +1,41 @@
+module Admin
+  class EffectiveQbReceiptsDatatable < Effective::Datatable
+    datatable do
+      order :updated_at
+
+      col :updated_at, visible: false
+      col :created_at, visible: false
+      col :id, visible: false
+
+      col :updated_at
+
+      col :order, search: :string
+
+      col :sales_receipt_id, label: 'QB Sales Receipt' do |receipt|
+        if receipt.sales_receipt_id.present?
+          link_to("Sales Receipt", api.sales_receipt_url(receipt.sales_receipt_id), target: '_blank')
+        end
+      end
+
+      col :customer_id, label: 'QB Customer' do |receipt|
+        if receipt.sales_receipt_id.present?
+          link_to("Customer", api.customer_url(receipt.customer_id), target: '_blank')
+        end
+      end
+
+      col :status
+      col :result
+
+      actions_col
+    end
+
+    collection do
+      Effective::QbReceipt.deep.all
+    end
+
+    def api
+      @api ||= EffectiveQbOnline.api
+    end
+
+  end
+end

data/app/helpers/effective_qb_online_helper.rb

@@ -0,0 +1,14 @@
+module EffectiveQbOnlineHelper
+  def qb_receipt_effective_orders_collection(qb_receipt)
+    raise('expected a non-persisted Effective::QbReceipt') unless qb_receipt.kind_of?(Effective::QbReceipt) && qb_receipt.new_record?
+
+    existing = Effective::QbReceipt.select('order_id')
+    orders = Effective::Order.purchased.sorted.includes(:user).where.not(id: existing)
+
+    orders.map do |order|
+      label = "#{order} - #{order.user} - #{price_to_currency(order.total)}"
+      [label, order.to_param]
+    end
+
+  end
+end

data/app/jobs/qb_sync_order_job.rb

@@ -0,0 +1,13 @@
+class QbSyncOrderJob < ApplicationJob
+  queue_as :default
+
+  def perform(order)
+    raise('expected a purchased Effective::Order') unless order.kind_of?(Effective::Order) && order.purchased?
+
+    puts "Starting QB Sync Order Job for order #{order}"
+
+    qb_receipt = Effective::QbReceipt.create_from_order!(order)
+    qb_receipt.sync!
+  end
+
+end

data/app/models/effective/qb_api.rb

@@ -0,0 +1,208 @@
+# The Quickbooks namespace comes from quickbooks-ruby gem
+# https://github.com/ruckus/quickbooks-ruby
+
+module Effective
+  class QbApi
+    attr_accessor :realm
+
+    def initialize(realm:)
+      raise('expected an Effective::QbRealm') unless realm.kind_of?(Effective::QbRealm)
+      @realm = realm
+    end
+
+    def app_url
+      Quickbooks.sandbox_mode ? 'https://app.sandbox.qbo.intuit.com/app' : 'https://app.qbo.intuit.com/app'
+    end
+
+    def sales_receipt_url(obj)
+      "#{app_url}/salesreceipt?txnId=#{obj.try(:sales_receipt_id) || obj.try(:id) || obj}"
+    end
+
+    def customer_url(obj)
+      "#{app_url}/customerdetail?nameId=#{obj.try(:customer_id) || obj.try(:id) || obj}"
+    end
+
+    def price_to_amount(price)
+      raise('Expected an Integer price') unless price.kind_of?(Integer)
+      (price / 100.0).round(2)
+    end
+
+    def build_address(address)
+      raise('Expected a Effective::Address') unless address.kind_of?(Effective::Address)
+
+      Quickbooks::Model::PhysicalAddress.new(
+        line1: address.address1,
+        line2: address.address2,
+        line3: address.try(:address3),
+        city: address.city,
+        country: address.country,
+        country_sub_division_code: address.country_code,
+        postal_code: address.postal_code
+      )
+    end
+
+    # Singular
+    def company_info
+      with_service('CompanyInfo') { |service| service.fetch_by_id(realm.realm_id) }
+    end
+
+    def accounts
+      with_service('Account') { |service| service.all }
+    end
+
+    # Only accounts we can use for the Deposit to Account setting
+    def accounts_collection
+      accounts
+        .select { |account| ['Bank', 'Other Current Asset'].include?(account.account_type) }
+        .sort_by { |account| [account.account_type, account.name] }
+        .map { |account| [account.name, account.id, account.account_type] }
+        .group_by(&:last)
+    end
+
+    def items
+      with_service('Item') { |service| service.all }
+    end
+
+    def items_collection
+      items
+        .reject { |item| item.type == 'Category' }
+        .sort_by { |item| [item.type, item.name] }
+        .map { |item| [item.name, item.id, item.type] }
+        .group_by(&:last)
+    end
+
+    def payment_methods
+      with_service('PaymentMethod') { |service| service.all }
+    end
+
+    def payment_methods_collection
+      payment_methods.sort_by(&:name).map { |payment_method| [payment_method.name, payment_method.id] }
+    end
+
+    def find_or_create_customer(user:)
+      find_customer(user: user) || create_customer(user: user)
+    end
+
+    def find_customer(user:)
+      raise('expected a user that responds to email') unless user.respond_to?(:email)
+
+      with_service('Customer') do |service|
+        # Find by email
+        customer = service.find_by(:PrimaryEmailAddr, user.email)&.first
+
+        # Find by given name and family name
+        customer ||= if user.respond_to?(:first_name) && user.respond_to?(:last_name)
+          service.query("SELECT * FROM Customer WHERE GivenName LIKE '#{scrub(user.first_name)}' AND FamilyName LIKE '#{scrub(user.last_name)}'")&.first
+        end
+
+        # Find by display name
+        customer || service.find_by(:display_name, scrub(user.to_s))&.first
+      end
+    end
+
+    def create_customer(user:)
+      raise('expected a user that responds to email') unless user.respond_to?(:email)
+
+      with_service('Customer') do |service|
+        customer = Quickbooks::Model::Customer.new(
+          primary_email_address: Quickbooks::Model::EmailAddress.new(user.email),
+          display_name: scrub(user.to_s),
+          given_name: scrub(user.try(:first_name)),
+          family_name: scrub(user.try(:last_name))
+        )
+
+        service.create(customer)
+      end
+    end
+
+    def delete_customer(customer:)
+      with_service('Customer') { |service| service.delete(customer) }
+    end
+
+    def create_sales_receipt(sales_receipt:)
+      with_service('SalesReceipt') { |service| service.create(sales_receipt) }
+    end
+
+    def find_sales_receipt(id:)
+      with_service('SalesReceipt') { |service| service.find_by(:id, id) }
+    end
+
+    def tax_codes
+      with_service('TaxCode') { |service| service.all }
+    end
+
+    def tax_rates
+      with_service('TaxRate') { |service| service.all }
+    end
+
+    # Returns a Hash of BigNumeral Tax Rate => TaxCode Object
+    # { 0.0 => Quickbooks::Model::TaxCode }
+    def taxes_collection
+      rates = tax_rates()
+      codes = tax_codes()
+
+      # Find Exempt 0.0
+      exempt = codes.find do |code|
+        rate_id = code.sales_tax_rate_list.tax_rate_detail.first&.tax_rate_ref&.value
+        rate = rates.find { |rate| rate.id == rate_id } if rate_id
+
+        code.name.downcase.include?('exempt') && rate && rate.rate_value == 0.0
+      end
+
+      exempt = [['0.0', exempt]] if exempt.present?
+
+      # Find The rest
+      tax_codes = codes.map do |code|
+        rate_id = code.sales_tax_rate_list.tax_rate_detail.first&.tax_rate_ref&.value
+        rate = rates.find { |rate| rate.id == rate_id } if rate_id
+
+        [rate.rate_value.to_s, code] if rate && (exempt.blank? || rate.rate_value > 0.0)
+      end
+
+      (Array(exempt) + tax_codes.compact).to_h
+    end
+
+    private
+
+    def with_service(name, &block)
+      klass = "Quickbooks::Service::#{name}".constantize
+
+      with_authenticated_request do |access_token|
+        service = klass.new(company_id: realm.realm_id, access_token: access_token)
+        yield(service)
+      end
+    end
+
+    def with_authenticated_request(max_attempts: 3, &block)
+      attempts = 0
+
+      begin
+        token = OAuth2::AccessToken.new(EffectiveQbOnline.oauth2_client, realm.access_token, refresh_token: realm.refresh_token)
+        yield(token)
+      rescue OAuth2::Error, Quickbooks::AuthorizationFailure => e
+        puts "Quickbooks OAuth Error: #{e.message}"
+
+        attempts += 1
+        raise "unable to refresh Quickbooks OAuth2 token" if attempts >= max_attempts
+
+        # Refresh
+        refreshed = token.refresh!
+
+        realm.update!(
+          access_token: refreshed.token,
+          refresh_token: refreshed.refresh_token,
+          access_token_expires_at: Time.at(refreshed.expires_at),
+          refresh_token_expires_at: (Time.at(refreshed.expires_at) + 100.days)
+        )
+
+        retry
+      end
+    end
+
+    def scrub(value)
+      return nil unless value.present?
+      value.gsub(':', '')
+    end
+
+  end
+end

data/app/models/effective/qb_realm.rb

@@ -0,0 +1,37 @@
+# One Quickbooks Realm / Company
+
+module Effective
+  class QbRealm < ActiveRecord::Base
+
+    effective_resource do
+      # As per Quickbooks oAuth
+      realm_id                    :string
+
+      access_token                :text
+      access_token_expires_at     :datetime
+
+      refresh_token               :text
+      refresh_token_expires_at    :datetime
+
+      # Set on /admin/quickbooks
+      deposit_to_account_id       :string
+      payment_method_id           :string
+
+      timestamps
+    end
+
+    validates :realm_id, presence: true
+    validates :realm_id, uniqueness: true, if: -> { new_record? }
+
+    validates :access_token, presence: true
+    validates :access_token_expires_at, presence: true
+
+    validates :refresh_token, presence: true
+    validates :refresh_token_expires_at, presence: true
+
+    def to_s
+      'Quickbooks Online Settings'
+    end
+
+  end
+end

data/app/models/effective/qb_receipt.rb

@@ -0,0 +1,98 @@
+module Effective
+  class QbReceipt < ActiveRecord::Base
+    belongs_to :order, class_name: 'Effective::Order'
+
+    log_changes if respond_to?(:log_changes)
+
+    has_many :qb_receipt_items, inverse_of: :qb_receipt, dependent: :delete_all
+    accepts_nested_attributes_for :qb_receipt_items
+
+    acts_as_statused(:todo, :completed, :errored, :skipped)
+
+    effective_resource do
+      # QuickBooks Customer
+      customer_id               :string
+
+      # Quickbooks Online SalesReceipt id, once sync'd
+      sales_receipt_id          :string
+
+      # Any error message from our sync
+      result                    :text
+
+      # Acts as Statused
+      status                    :string
+      status_steps              :text
+
+      timestamps
+    end
+
+    scope :deep, -> { includes(order: :user, qb_receipt_items: [order_item: :purchasable]) }
+
+    # Create a QbReceiptItem for each OrderItem
+    before_validation(if: -> { order.present? }) do
+      order.order_items.each { |order_item| qb_receipt_item(order_item: order_item) }
+    end
+
+    validates :qb_receipt_items, presence: true
+
+    with_options(if: -> { completed? }) do
+      validates :customer_id, presence: true
+      validates :sales_receipt_id, presence: true
+    end
+
+    # Create a QbReceipt from an Effective::Order
+    def self.create_from_order!(order)
+      raise('Expected a purchased Effective::Order') unless order.kind_of?(Effective::Order) && order.purchased?
+      Effective::QbReceipt.where(order: order).first_or_create
+    end
+
+    def to_s
+      order.to_s
+    end
+
+    # Find or build
+    def qb_receipt_item(order_item:)
+      qb_receipt_items.find { |item| item.order_item == order_item } ||
+      qb_receipt_items.build(order_item: order_item)
+    end
+
+    def sync!(force: false)
+      raise('Already created SalesReceipt with Quickbooks Online') if sales_receipt_id.present? && !force
+      save!
+
+      api = EffectiveQbOnline.api
+
+      begin
+        sales_receipt = Effective::QbSalesReceipt.build_from_receipt!(self, api: api)
+        sales_receipt = api.create_sales_receipt(sales_receipt: sales_receipt)
+
+        # Sanity check
+        if (expected = api.price_to_amount(order.total)) != sales_receipt.total
+          raise("A Quickbooks Online Sales Receipt has been created with an unexpected total. Quickbooks total is #{sales_receipt.total} but we expected #{expected}. Please adjust the Sales Receipt on Quickbooks")
+        end
+
+        assign_attributes(result: 'completed successfully', sales_receipt_id: sales_receipt.id)
+        complete!
+      rescue => e
+        assign_attributes(result: e.message)
+        error!
+      end
+
+      true
+    end
+
+    def skip!
+      assign_attributes(result: 'skipped')
+      skipped!
+    end
+
+    def complete!
+      completed!
+    end
+
+    def error!
+      errored!
+    end
+
+  end
+end