solidus_bactracs 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4b7e4705f8b153de50fd8758b429b25bb10aaac9026ee0623fcb3fb4abab3fbb
+  data.tar.gz: 4ce4611fba9dbc776d89800e081f95221b71019ad6d04200f0cc171957a18a21
+SHA512:
+  metadata.gz: 17c8b9f6e4ee8523d4f9fa69c7608a87bbed339ec4ba2afd26c0f071d9da0db84cf3e371604c26c4e9dec84bb41d4f66646ee14ec229740c2bbffd2c31d67eb2
+  data.tar.gz: 6891b4cff40267a4f8762b271fa1a69633c3b0f658ccda99dbce45941b56d8895f9ecaef0dbb0f91597271c880cb66f6545e396c98c74ac98f64577484a23193

data/.bundle/config

@@ -0,0 +1,2 @@
+---
+BUNDLE_JOBS: "12"

data/.circleci/config.yml

@@ -0,0 +1,41 @@
+version: 2.1
+
+orbs:
+  # Always take the latest version of the orb, this allows us to
+  # run specs against Solidus supported versions only without the need
+  # to change this configuration every time a Solidus version is released
+  # or goes EOL.
+  solidusio_extensions: solidusio/extensions@volatile
+
+jobs:
+  run-specs-with-postgres:
+    executor: solidusio_extensions/postgres
+    steps:
+      - solidusio_extensions/run-tests
+  run-specs-with-mysql:
+    executor: solidusio_extensions/mysql
+    steps:
+      - solidusio_extensions/run-tests
+  lint-code:
+    executor: solidusio_extensions/sqlite-memory
+    steps:
+      - solidusio_extensions/lint-code
+
+workflows:
+  "Run specs on supported Solidus versions":
+    jobs:
+      - run-specs-with-postgres
+      - run-specs-with-mysql
+      - lint-code
+
+  "Weekly run specs against master":
+    triggers:
+      - schedule:
+          cron: "0 0 * * 4" # every Thursday
+          filters:
+            branches:
+              only:
+                - master
+    jobs:
+      - run-specs-with-postgres
+      - run-specs-with-mysql

data/.gem_release.yml

@@ -0,0 +1,5 @@
+bump:
+  recurse: false
+  file: 'lib/solidus_backtracs/version.rb'
+  message: Bump SolidusBacktracs to %{version}
+  tag: true

data/.github/stale.yml

@@ -0,0 +1,17 @@
+# Number of days of inactivity before an issue becomes stale
+daysUntilStale: 60
+# Number of days of inactivity before a stale issue is closed
+daysUntilClose: false
+# Issues with these labels will never be considered stale
+exemptLabels:
+  - pinned
+  - security
+# Label to use when marking an issue as stale
+staleLabel: stale
+# Comment to post when marking an issue as stale. Set to `false` to disable
+markComment: >
+  This issue has been automatically marked as stale because it has not had
+  recent activity. It might be closed if no further activity occurs. Thank you
+  for your contributions.
+# Comment to post when closing a stale issue. Set to `false` to disable
+closeComment: false

data/.github_changelog_generator

@@ -0,0 +1,2 @@
+issues=false
+exclude-labels=infrastructure

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+\#*
+*~
+.#*
+.DS_Store
+.idea
+.project
+.sass-cache
+coverage
+Gemfile.lock
+tmp
+nbproject
+pkg
+*.swp
+spec/dummy
+spec/examples.txt
+/sandbox
+.rvmrc
+.ruby-version
+.ruby-gemset
+.tool-versions
+TAGS

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,14 @@
+inherit_from: .rubocop_todo.yml
+
+require:
+  - solidus_dev_support/rubocop
+
+AllCops:
+  NewCops: disable
+  TargetRubyVersion: 2.5
+
+Layout/LineLength:
+  Enabled: false
+
+Rails/SkipsModelValidations:
+  Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,40 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2020-09-22 09:09:44 UTC using RuboCop version 0.87.1.
+# 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.
+
+# Offense count: 1
+Lint/UselessAssignment:
+  Exclude:
+    - 'app/controllers/spree/backtracs_controller.rb'
+
+# Offense count: 1
+RSpec/AnyInstance:
+  Exclude:
+    - 'spec/lib/solidus_backtracs/shipment_notice_spec.rb'
+
+# Offense count: 5
+RSpec/MultipleExpectations:
+  Max: 2
+
+# Offense count: 8
+RSpec/NestedGroups:
+  Max: 5
+
+# Offense count: 6
+# Configuration parameters: ForbiddenMethods, AllowedMethods.
+# ForbiddenMethods: decrement!, decrement_counter, increment!, increment_counter, insert, insert!, insert_all, insert_all!, toggle!, touch, touch_all, update_all, update_attribute, update_column, update_columns, update_counters, upsert, upsert_all
+Rails/SkipsModelValidations:
+  Exclude:
+    - 'spec/lib/solidus_backtracs/shipment_notice_spec.rb'
+    - 'spec/models/spree/shipment_spec.rb'
+    - 'spec/support/shipment_helper.rb'
+
+# Offense count: 1
+# Configuration parameters: MinBodyLength.
+Style/GuardClause:
+  Exclude:
+    - 'spec/support/configuration_helper.rb'

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 2.2.0
+
+Support the Solidus Assembly gem, consider allowed SKUs within assemblies/bundles
+Retry logic for the authenticated request
+
+## 2.1.0
+
+New auth and API patterns for Backtracs
+Support specific SKUs to be mapped
+
+## 2.0.0
+
+Diverged the gem from Shipstation to the Bactracs API
+

data/Gemfile

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+branch = ENV.fetch('SOLIDUS_BRANCH', 'master')
+gem 'solidus', github: 'solidusio/solidus', branch: branch
+
+# Needed to help Bundler figure out how to resolve dependencies,
+# otherwise it takes forever to resolve them.
+# See https://github.com/bundler/bundler/issues/6677
+gem 'rails', '>0.a'
+
+# Provides basic authentication functionality for testing parts of your engine
+gem 'solidus_auth_devise'
+
+case ENV['DB']
+when 'mysql'
+  gem 'mysql2'
+when 'postgresql'
+  gem 'pg'
+else
+  gem 'sqlite3'
+end
+
+gemspec
+
+# Use a local Gemfile to include development dependencies that might not be
+# relevant for the project or for other contributors, e.g. pry-byebug.
+#
+# We use `send` instead of calling `eval_gemfile` to work around an issue with
+# how Dependabot parses projects: https://github.com/dependabot/dependabot-core/issues/1658.
+send(:eval_gemfile, 'Gemfile-local') if File.exist? 'Gemfile-local'

data/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2013 Boomer Digital
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name Solidus nor the names of its contributors may be used to
+      endorse or promote products derived from this software without specific
+      prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,216 @@
+# Solidus Bactracs
+
+
+This gem integrates [Bactracs](http://www.backtracs.com) with [Solidus](http://solidus.io). It
+enables your Solidus system to push shipment RMAs to the system.
+
+> This integration was cloned from [spree_shipstation](https://github.com/DynamoMTL/spree_shipstation) to provide some consistency with other Solidus<-->Shipping related patterns.
+
+## Installation
+
+Add solidus_bactracs to your Gemfile:
+
+```ruby
+gem 'solidus_bactracs', github: 'suvie-eng/solidus_bactracs'
+```
+
+Bundle your dependencies and run the installation generator:
+
+```shell
+bin/rails generate solidus_bactracs:install
+```
+
+The installer will create a configuration initializer that you'll need to customize.
+
+The installer will also create a migration, which is required by the API integration. If you are
+going to use the XML integration, feel free to delete the migration file, as those columns won't be
+used by the extension.
+
+## Usage
+
+This extension can integrate with ShipStation in two ways.
+
+### XML integration
+
+The [XML integration](https://help.backtracs.com/hc/en-us/articles/360025856192-Custom-Store-Development-Guide)
+works by exposing a route in your Solidus application that generates an XML feed of all recently
+created and updated shipments in your Solidus store.
+
+#### XML integration: Configuration
+
+⛔️ This section is outdated and inaccurate.
+
+In order to enable the XML integration, make sure to configure the relevant section of the
+configuration initializer, and configure your ShipStation store accordingly:
+
+- **Username**: the username defined in your configuration.
+- **Password**: the password defined in your configuration.
+- **URL to custom page**: `https://yourdomain.com/backtracs.xml`.
+
+You can also configure your ShipStation store to pull the XML feed automatically on a recurring
+basis, or manually by clicking the "Refresh stores" button.
+
+There are five shipment states for an order (= shipment) in ShipStation. These states do not
+necessarily align with Solidus, but you can configure ShipStation to create a mapping for your
+specific needs. Here's the recommended mapping:
+
+Bactracs description    | Bactracs status    | Solidus status
+------------------------|--------------------|---------------
+Awaiting Payment        | `unpaid`           | `pending`
+Awaiting Shipment       | `paid`             | `ready`
+Shipped                 | `shipped`          | `shipped`
+Cancelled               | `cancelled`        | `cancelled`
+On-Hold                 | `on-hold`          | `pending`
+
+Once you've configured the XML integration in your app and ShipStation, there's nothing else you
+need to do. ShipStation will
+
+#### XML integration: Usage
+
+There's nothing you need to do. Once properly configured, the integration just works!
+
+#### XML integration: Gotchas
+
+There are a few gotchas you need to be aware of:
+
+- If you change the shipping method of an order in ShipStation, the change will not be reflected in
+  Solidus and the tracking link might not work properly.
+- When `bactracs_capture_at_notification` is enabled, any errors during payment capture will
+  prevent the update of the shipment's tracking number.
+
+### API integration
+
+The [API integration](https://www.backtracs.com/docs/api/) works by calling the ShipStation API
+to sync all of your shipments continuously.
+
+Because ShipStation has very low rate limits (i.e., 40 reqs/minute at the time of writing), the
+API integration does not send an API request for every single shipment update, as you would expect
+from a traditional API integration.
+
+Instead, a background job runs on a recurring basis and batches together all the shipments that need
+to be created or updated in ShipStation. These shipments are then sent in groups of 100 (by default)
+to ShipStation's [bulk order upsert endpoint](https://www.backtracs.com/docs/api/orders/create-update-multiple-orders/).
+
+This allows us to work around Bactracs's rate limit and sync up to 4000 shipments/minute.
+
+As you may imagine, this technique also comes at the expense of some additional complexity in the
+implementation, but the extension abstracts it all away for you.
+
+#### API integration: Configuration
+
+In order to enable the API integration, make sure to configure the relevant section of the
+configuration initializer. At the very least, the integration needs to know your API credentials
+and store ID, but there are additional options you can configure — just look at the initializer!
+
+#### API integration: Usage
+
+Once you've configured the integration, you will also need to enqueue the `ScheduleShipmentSyncsJob`
+on a recurring basis, to kick off the synchronization process. Because every app uses a different
+background processing library, this is left up to the user.
+
+Here's what an example with [sidekiq-scheduler](https://github.com/moove-it/sidekiq-scheduler) might
+look like:
+
+```yaml
+# config/sidekiq.yml
+:schedule:
+  schedule_shipment_syncs:
+    every: ['1m', first_in: '0s']
+    class: 'SolidusBactracs::Api::ScheduleShipmentSyncsJob'
+```
+
+This will schedule the job to run every minute. This is generally a good starting point, but feel
+free to adjust it as needed.
+
+#### API integration: Gotchas
+
+One of the main issues to be aware of is that the Bactracs API *always* responds with an HTTP 200, even if the request failed.  This may be a SOAP convention, or just the idiosyncrasies of the API design.
+
+⚠️ You must always inspect the `Message` component of the response in order to determine success/fail.  THe e.g. `Result` field can say "true" but the Message states a failure.
+
+----
+
+There other factor you need to be aware of when integrating via the API:  the interval between your syncs is, on average, larger than your latency in processing background jobs, or you are going to experience sync overlaps.
+
+As an example, if it takes your Sidekiq process 10 seconds to execute a job from the time it's
+scheduled, but you schedule a shipment sync every 5 seconds, your sync jobs will start overlapping,
+making your latency even worse.
+
+This is a problem that is faced by all recurring jobs. The solution is two-fold:
+
+1. Monitor the latency of your background processing queues. Seriously, do it.
+2. Make sure your sync interval is not too aggressive: unless you really need to, there's no point
+   in syncing your shipments more often than once a minute.
+
+## Development
+
+### Testing the extension
+
+
+⛔️ This section is outdated and inaccurate.
+
+First bundle your dependencies, then run `bin/rake`. `bin/rake` will default to building the dummy
+app if it does not exist, then it will run specs. The dummy app can be regenerated by using
+`bin/rake extension:test_app`.
+
+```shell
+bin/rake
+```
+
+To run [Rubocop](https://github.com/bbatsov/rubocop) static code analysis run
+
+```shell
+bundle exec rubocop
+```
+
+When testing your application's integration with this extension you may use its factories.
+Simply add this require statement to your `spec/spec_helper.rb`:
+
+```ruby
+require 'solidus_bactracs/testing_support/factories'
+```
+
+Or, if you are using `FactoryBot.definition_file_paths`, you can load Solidus core
+factories along with this extension's factories using this statement:
+
+```ruby
+SolidusDevSupport::TestingSupport::Factories.load_for(SolidusBactracs::Engine)
+```
+
+### Running the sandbox
+
+
+⛔️ This section is outdated and inaccurate.
+
+To run this extension in a sandboxed Solidus application, you can run `bin/sandbox`. The path for
+the sandbox app is `./sandbox` and `bin/rails` will forward any Rails commands to
+`sandbox/bin/rails`.
+
+Here's an example:
+
+```
+$ bin/rails server
+=> Booting Puma
+=> Rails 6.0.2.1 application starting in development
+* Listening on tcp://127.0.0.1:3000
+Use Ctrl-C to stop
+```
+
+### Updating the changelog
+
+Before and after releases the changelog should be updated to reflect the up-to-date status of
+the project:
+
+```shell
+bin/rake changelog
+git add CHANGELOG.md
+git commit -m "Update the changelog"
+```
+
+### Releasing new versions
+
+Please refer to the dedicated [page](https://github.com/solidusio/solidus/wiki/How-to-release-extensions) on Solidus wiki.
+
+## License
+
+Copyright (c) 2022 Suvie, released under the New BSD License.

data/Rakefile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'solidus_dev_support/rake_tasks'
+SolidusDevSupport::RakeTasks.install
+
+task default: 'extension:specs'

data/app/assets/javascripts/spree/backend/solidus_backtracs.js

@@ -0,0 +1,2 @@
+// Placeholder manifest file.
+// the installer will append this file to the app vendored assets here: vendor/assets/javascripts/spree/backend/all.js'

data/app/assets/javascripts/spree/frontend/solidus_backtracs.js

@@ -0,0 +1,2 @@
+// Placeholder manifest file.
+// the installer will append this file to the app vendored assets here: vendor/assets/javascripts/spree/frontend/all.js'

data/app/assets/stylesheets/spree/backend/solidus_backtracs.css

@@ -0,0 +1,4 @@
+/*
+Placeholder manifest file.
+the installer will append this file to the app vendored assets here: 'vendor/assets/stylesheets/spree/backend/all.css'
+*/

data/app/assets/stylesheets/spree/frontend/solidus_backtracs.css

@@ -0,0 +1,4 @@
+/*
+Placeholder manifest file.
+the installer will append this file to the app vendored assets here: 'vendor/assets/stylesheets/spree/frontend/all.css'
+*/

data/app/controllers/spree/backtracs_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Spree
+  class BacktracsController < Spree::BaseController
+    protect_from_forgery with: :null_session, only: :shipnotify
+
+    before_action :authenticate_backtracs
+
+    def export
+      @shipments = SolidusBacktracs::Shipment::ExportableQuery.apply(Spree::Shipment.all)
+      @shipments = SolidusBacktracs::Shipment::BetweenQuery.apply(
+        @shipments,
+        from: date_param(:start_date),
+        to: date_param(:end_date),
+      )
+      @shipments = @shipments.page(params[:page]).per(50)
+
+      respond_to do |format|
+        format.xml { render layout: false }
+      end
+    end
+
+    def shipnotify
+      shipment_notice_class = SolidusBacktracs.configuration.shipment_notice_class.constantize
+      shipment_notice_class.from_payload(params.to_unsafe_h).apply
+      head :ok
+    rescue SolidusBacktracs::Error => e
+      head :bad_request
+    end
+
+    private
+
+    def date_param(name)
+      return if params[name].blank?
+
+      Time.strptime("#{params[name]} UTC", '%m/%d/%Y %H:%M %Z')
+    end
+
+    def authenticate_backtracs
+      authenticate_or_request_with_http_basic do |username, password|
+        username == SolidusBacktracs.configuration.username &&
+          password == SolidusBacktracs.configuration.password
+      end
+    end
+  end
+end

data/app/decorators/models/solidus_backtracs/spree/shipment_decorator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SolidusBacktracs
+  module Spree
+    module ShipmentDecorator
+      def self.prepended(base)
+        base.singleton_class.prepend ClassMethods
+      end
+
+      module ClassMethods
+        def exportable
+          ::Spree::Deprecation.warn <<~DEPRECATION
+            `Spree::Shipment.exportable` is deprecated and will be removed in a future version
+            of solidus_backtracs. Please use `SolidusBacktracs::Shipment::ExportableQuery.apply`.
+          DEPRECATION
+
+          SolidusBacktracs::Shipment::ExportableQuery.apply(self)
+        end
+
+        def between(from, to)
+          ::Spree::Deprecation.warn <<~DEPRECATION
+            `Spree::Shipment.between` is deprecated and will be removed in a future version
+            of solidus_backtracs. Please use `SolidusBacktracs::Shipment::BetweenQuery.apply`.
+          DEPRECATION
+
+          SolidusBacktracs::Shipment::BetweenQuery.apply(self, from: from, to: to)
+        end
+      end
+
+      ::Spree::Shipment.prepend self
+    end
+  end
+end

data/app/helpers/solidus_backtracs/export_helper.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'builder'
+
+module SolidusBacktracs
+  module ExportHelper
+    DATE_FORMAT = '%m/%d/%Y %H:%M'
+    BACTRACS_DATE_FORMAT = '%Y-%m-%dT%H:%M:%S'
+
+    # rubocop:disable all
+    def self.address(xml, order, type)
+      name = "#{type.to_s.titleize}To"
+      address = order.send("#{type}_address")
+
+      xml.__send__(name) {
+        xml.Name         address.respond_to?(:name) ? address.name : address.full_name
+        xml.Company      address.company
+
+        if type == :ship
+          xml.Address1   address.address1
+          xml.Address2   address.address2
+          xml.City       address.city
+          xml.State      address.state ? address.state.abbr : address.state_name
+          xml.PostalCode address.zipcode
+          xml.Country    address.country.iso
+        end
+
+        xml.Phone        address.phone
+      }
+    end
+
+    def self.backtracs_address(xml, order, type)
+      address = order.send("#{type}_address")
+      if address.present?
+        name = "#{type.to_s.titleize}To"
+
+        xml.__send__(name) {
+          xml.CompanyName   address.company ? address.company : address.name
+          xml.Contact       address.name
+          xml.ContactEmail  order.email
+          xml.Address1      address.address1
+          xml.Address2      address.address2
+          xml.City          address.city
+          xml.State         address.state ? address.state.abbr : address.state_name
+          xml.Zip           address.zipcode
+          xml.Phone         address.phone.present? ? address.phone : "000-000-0000"
+          xml.PhoneAlt      address.phone.present? ? address.phone : "000-000-0000"
+          xml.Country       address.country.iso
+        }
+      else
+        Rails.logger.info({
+          message: 'missing address type',
+          order: order.id,
+          type: type
+        }.to_s)
+      end
+    end
+    # rubocop:enable all
+  end
+end

data/app/jobs/solidus_backtracs/api/schedule_shipment_syncs_job.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SolidusBacktracs
+  module Api
+    class ScheduleShipmentSyncsJob < ApplicationJob
+      queue_as :default
+
+      def perform
+        shipments = query_shipments
+        Rails.logger.info("#{self.class.name} - #{shipments.count} shipments to sync to Bactracs")
+
+        shipments.find_in_batches(batch_size: SolidusBacktracs.config.api_batch_size) do |batch|
+          SyncShipmentsJob.perform_later(batch.to_a)
+        end
+      rescue StandardError => e
+        SolidusBacktracs.config.error_handler.call(e, {})
+      end
+
+      def shippable_skus
+        SolidusBacktracs.config.shippable_skus.present? ? SolidusBacktracs.config.shippable_skus : Spree::Variant.pluck(:sku)
+      end
+
+      def query_shipments
+        shipments = SolidusBacktracs::Shipment::PendingApiSyncQuery.apply(
+          ::Spree::Shipment
+            .joins(inventory_units: [:variant])
+            .where("spree_variants.sku" => SolidusBacktracs.config.shippable_skus)
+            .where("spree_shipments.state" => :ready)
+            .where(backtracs_synced_at: nil)
+            .distinct
+        )
+      end
+    end
+  end
+end
+