spree-shipstation 5.0.0

data/app/models/spree/integrations/shipstation.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Spree
+  module Integrations
+    class Shipstation < Spree::Integration
+      preference :username, :string
+
+      validates :preferred_username,
+        presence: true,
+        length: {minimum: 10, maximum: 30}
+
+      # Restrict to characters that are safe to send in an HTTP Basic Auth header:
+      # a-z, A-Z, 0-9, and . _ @ + -
+      validates :preferred_username,
+        format: {
+          with: /\A[a-zA-Z0-9._@+-]+\z/,
+          message: Spree.t("admin.integrations.shipstation.username_chars_error")
+        },
+        allow_blank: true
+
+      preference :password, :password
+
+      validates :preferred_password,
+        presence: true,
+        length: {minimum: 20, maximum: 60}
+
+      validates :preferred_password,
+        format: {
+          with: /[!@#$%^&*(),.?":{}|<>]/,
+          message: Spree.t("admin.integrations.shipstation.must_contain_at_least_one_special_character")
+        },
+        allow_blank: true
+
+      validates :preferred_password,
+        format: {
+          with: /[A-Z]/,
+          message: Spree.t("admin.integrations.shipstation.must_contain_at_least_one_uppercase_letter")
+        },
+        allow_blank: true
+
+      validates :preferred_password,
+        format: {
+          with: /\d/,
+          message: Spree.t("admin.integrations.shipstation.must_contain_at_least_one_number")
+        },
+        allow_blank: true
+
+      def self.integration_group
+        "Shipping"
+      end
+
+      def self.icon_path
+        "integration_icons/shipstation-logo.webp"
+      end
+
+      def self.integration_name
+        Spree.t("admin.integrations.shipstation.brand_name")
+      end
+    end
+  end
+end

data/app/models/spree/shipment_decorator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Spree
+  module ShipmentDecorator
+    def self.prepended(base)
+      base.scope :exportable, lambda {
+        joins(:order)
+          .merge(::Spree::Order.complete)
+          .where(state: "ready")
+          .order(:updated_at)
+          .includes(:order, inventory_units: {line_item: {variant: [:product, :images, {option_values: :option_type}]}})
+      }
+
+      base.scope :between, lambda { |from, to|
+        return all if from.nil? && to.nil?
+
+        range = from..to
+
+        shipment_match = joins(:order).where(updated_at: range)
+        order_match = joins(:order).where(spree_orders: {updated_at: range})
+
+        shipment_match.or(order_match).distinct
+      }
+    end
+
+    ::Spree::Shipment.prepend self
+  end
+end

data/app/presenters/spree/shipstation/export/item_presenter.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Spree
+  module Shipstation
+    module Export
+      # Shapes a shipment line item (a line item plus its inventory units) into the
+      # values ShipStation's export XML expects for an <Item>.
+      class ItemPresenter
+        attr_reader :line_item, :units
+
+        def initialize(line_item, units)
+          @line_item = line_item
+          @units = units
+        end
+
+        def variant
+          @variant ||= line_item.variant
+        end
+
+        def sku
+          variant.sku
+        end
+
+        def name
+          [variant.product.name, variant.options_text].reject(&:blank?).join(" ")
+        end
+
+        # The Spree::Image to advertise, or nil. URL generation stays in the view
+        # because it depends on Rails route/URL helpers.
+        def image
+          variant.images.first || variant.product.master.images.first
+        end
+
+        def weight
+          Weight.from_variant(variant)
+        end
+
+        def quantity
+          units.size
+        end
+
+        def unit_price
+          line_item.price
+        end
+
+        def option_values
+          variant.option_values
+        end
+      end
+    end
+  end
+end

data/app/presenters/spree/shipstation/export/order_presenter.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Spree
+  module Shipstation
+    module Export
+      # Shapes a single Spree::Shipment into the values ShipStation's export XML
+      # expects, keeping data-massaging logic out of the Builder template.
+      #
+      # Note: ShipStation models one "Order" per shipment, so most order-level
+      # fields are derived from `shipment.order` while identifiers come from the
+      # shipment itself (mirroring the <OrderNumber> = shipment.number contract).
+      class OrderPresenter
+        attr_reader :shipment
+
+        def initialize(shipment)
+          @shipment = shipment
+        end
+
+        def order
+          shipment.order
+        end
+
+        def order_id
+          shipment.id
+        end
+
+        def order_number
+          shipment.number
+        end
+
+        def order_status
+          shipment.state
+        end
+
+        def order_date
+          format_date(order.completed_at)
+        end
+
+        def last_modified
+          format_date([order.completed_at, shipment.updated_at].compact.max)
+        end
+
+        def shipping_method_name
+          shipment.shipping_method&.name
+        end
+
+        def order_total
+          order.total
+        end
+
+        def tax_total
+          order.tax_total
+        end
+
+        def ship_total
+          order.ship_total
+        end
+
+        def custom_field_1
+          order.number
+        end
+
+        def customer_code
+          order.email&.slice(0, 50)
+        end
+
+        def bill_address
+          order.bill_address
+        end
+
+        def ship_address
+          order.ship_address
+        end
+
+        def items
+          shipment.inventory_units.group_by(&:line_item).filter_map do |line_item, units|
+            next unless line_item.variant
+
+            ItemPresenter.new(line_item, units)
+          end
+        end
+
+        private
+
+        def format_date(time)
+          time&.strftime(ExportHelper::DATE_FORMAT)
+        end
+      end
+    end
+  end
+end

data/app/presenters/spree/shipstation/export/weight.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Spree
+  module Shipstation
+    module Export
+      # Value object converting a Spree::Variant's weight into the
+      # (value, unit-label) pair ShipStation's export XML expects.
+      #
+      # ShipStation accepts Pounds, Ounces, and Grams; any unrecognised Spree
+      # weight unit (including a missing weight) falls back to Grams.
+      class Weight
+        attr_reader :value, :units
+
+        def initialize(value:, units:)
+          @value = value
+          @units = units
+        end
+
+        def self.from_variant(variant)
+          amount = (variant.weight || 0.0).to_f
+
+          case variant.weight_unit
+          when "lb"
+            new(value: amount, units: "Pounds")
+          when "oz"
+            new(value: amount, units: "Ounces")
+          when "kg"
+            new(value: amount * 1000, units: "Grams")
+          else
+            new(value: amount, units: "Grams")
+          end
+        end
+
+        def ==(other)
+          other.is_a?(self.class) && value == other.value && units == other.units
+        end
+        alias_method :eql?, :==
+
+        def hash
+          [value, units].hash
+        end
+      end
+    end
+  end
+end

data/app/views/spree/admin/integrations/forms/_shipstation.html.erb

@@ -0,0 +1,6 @@
+<div class="card mb-4">
+  <div class="card-body">
+    <%= preference_field(@integration, form, 'username', i18n_scope: 'admin.integrations.shipstation') %>
+    <%= preference_field(@integration, form, 'password', i18n_scope: 'admin.integrations.shipstation') %>
+  </div>
+</div>

data/app/views/spree/shipstation/export.xml.builder

@@ -0,0 +1,59 @@
+xml.instruct!
+
+xml.Orders(pages: @pagy.pages) do
+  @shipments.each do |shipment|
+    order = Spree::Shipstation::Export::OrderPresenter.new(shipment)
+
+    xml.Order do
+      xml.OrderID order.order_id
+      xml.OrderNumber order.order_number
+
+      xml.OrderDate order.order_date
+      xml.OrderStatus order.order_status
+      xml.LastModified order.last_modified
+
+      xml.ShippingMethod order.shipping_method_name
+      xml.OrderTotal order.order_total
+      xml.TaxAmount order.tax_total
+      xml.ShippingAmount order.ship_total
+      xml.CustomField1 order.custom_field_1
+
+      xml.Customer do
+        xml.CustomerCode order.customer_code
+        Spree::Shipstation::ExportHelper.bill_address(xml, order.bill_address)
+        Spree::Shipstation::ExportHelper.ship_address(xml, order.ship_address)
+      end
+
+      xml.Items do
+        order.items.each do |item|
+          weight = item.weight
+          image = item.image
+
+          xml.Item do
+            xml.SKU item.sku
+            xml.Name item.name
+
+            image_url = image && url_for(image.attachment)
+            xml.ImageUrl image_url if image_url
+
+            xml.Weight weight.value
+            xml.WeightUnits weight.units
+            xml.Quantity item.quantity
+            xml.UnitPrice item.unit_price
+
+            if item.option_values.present?
+              xml.Options do
+                item.option_values.each do |value|
+                  xml.Option do
+                    xml.Name value.option_type.presentation
+                    xml.Value value.name
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/bin/rails

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# This command will automatically be run when you run "rails" from the root of your extension
+
+ENGINE_ROOT = File.expand_path('..', __dir__)
+ENGINE_PATH = File.expand_path('../lib/spree/shipstation/engine', __dir__)
+
+require 'rails/all'
+require 'rails/engine/commands'

data/config/initializers/spree.rb

@@ -0,0 +1,3 @@
+Rails.application.config.after_initialize do
+  Rails.application.config.spree.integrations << Spree::Integrations::Shipstation
+end

data/config/locales/en.yml

@@ -0,0 +1,15 @@
+---
+en:
+  spree:
+    admin:
+      integrations:
+        shipstation:
+          must_contain_at_least_one_special_character: must contain at least one special character
+          must_contain_at_least_one_uppercase_letter: must contain at least one uppercase letter
+          must_contain_at_least_one_number: must contain at least one number
+          username_chars_error: can only contain letters, numbers, and . _ @ + -
+          username: Username
+          password: Password
+          brand_name: ShipStation
+          description: Integrate with ShipStation to automate your shipping workflows from a single dashboard.
+          capture_at_notification: Capture payment when shipment notification received from ShipStation

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Spree::Core::Engine.add_routes do
+  get "/shipstation", to: "shipstation#export"
+  post "/shipstation", to: "shipstation#shipnotify"
+end

data/gemfiles/spree_5_2.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "benchmark"
+gem "brakeman", require: false
+gem "bundler-audit", require: false
+gem "propshaft"
+gem "rails-controller-testing"
+gem "rspec-xsd"
+gem "spree_dev_tools"
+gem "standard"
+gem "sqlite3"
+gem "spree", "~> 5.2.0"
+gem "spree_admin", "~> 5.2.0"
+
+gemspec path: "../"

data/gemfiles/spree_5_3.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "benchmark"
+gem "brakeman", require: false
+gem "bundler-audit", require: false
+gem "propshaft"
+gem "rails-controller-testing"
+gem "rspec-xsd"
+gem "spree_dev_tools"
+gem "standard"
+gem "sqlite3"
+gem "spree", "~> 5.3.0"
+gem "spree_admin", "~> 5.3.0"
+
+gemspec path: "../"

data/gemfiles/spree_5_4.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "benchmark"
+gem "brakeman", require: false
+gem "bundler-audit", require: false
+gem "propshaft"
+gem "rails-controller-testing"
+gem "rspec-xsd"
+gem "spree_dev_tools"
+gem "standard"
+gem "sqlite3"
+gem "spree", "~> 5.4.0"
+gem "spree_admin", "~> 5.4.0"
+
+gemspec path: "../"

data/lib/spree/shipstation/engine.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Spree
+  module Shipstation
+    class Engine < ::Rails::Engine
+      require "spree/core"
+      isolate_namespace Spree
+
+      # Deliberately not "spree-shipstation": engine_name generates route helper
+      # prefixes and must be a valid Ruby identifier, so it cannot contain a dash.
+      engine_name "spree_shipstation"
+
+      # use rspec for tests
+      config.generators do |g|
+        g.test_framework :rspec
+      end
+
+      initializer "spree_shipstation.assets" do |app|
+        app.config.assets.precompile += %w[spree_shipstation_manifest] if app.config.respond_to?(:assets)
+      end
+
+      def self.activate
+        # Three levels up from lib/spree/shipstation/ to reach the gem root.
+        Dir.glob(File.join(File.dirname(__FILE__), "../../../app/**/*_decorator*.rb")).sort.each do |c|
+          Rails.configuration.cache_classes ? require(c) : load(c)
+        end
+      end
+
+      config.to_prepare(&method(:activate).to_proc)
+    end
+  end
+end

data/lib/spree/shipstation/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Spree
+  module Shipstation
+    class Error < StandardError; end
+
+    class ShipmentNotFoundError < Error
+      def initialize(shipment_number, *args)
+        super("Could not find shipment with number #{shipment_number}", *args)
+      end
+    end
+
+    class PaymentError < Error
+      def initialize(payment, *args)
+        super("Could not process payment #{payment.id}", *args)
+      end
+    end
+
+    class MissingTrackingNumberError < Error
+      def initialize(*args)
+        super("Tracking number is required", *args)
+      end
+    end
+  end
+end

data/lib/spree/shipstation/factories.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Dir["#{File.dirname(__FILE__)}/testing_support/factories/**"].each do |f|
+  load File.expand_path(f)
+end

data/lib/spree/shipstation/shipment_notice.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Spree
+  module Shipstation
+    class ShipmentNotice
+      attr_reader :shipment_number, :shipment_tracking, :store
+
+      class << self
+        def from_payload(params, store:)
+          new(
+            # ShipStation's webhook param is named `order_number` but its value is the
+            # shipment number — it mirrors the <OrderNumber> field from the export XML.
+            shipment_number: params[:order_number],
+            shipment_tracking: params[:tracking_number],
+            store: store
+          )
+        end
+      end
+
+      def initialize(shipment_number:, shipment_tracking:, store:)
+        @shipment_number = shipment_number
+        @shipment_tracking = shipment_tracking
+        @store = store
+      end
+
+      def apply
+        raise ShipmentNotFoundError, shipment_number unless shipment
+
+        ::Spree::Shipment.transaction do
+          ship_shipment
+        end
+
+        shipment
+      end
+
+      private
+
+      def shipment
+        @shipment ||= store.shipments.find_by(number: shipment_number)
+      end
+
+      def ship_shipment
+        raise MissingTrackingNumberError if shipment_tracking.blank?
+
+        # Payment capture is performed synchronously, inside the webhook request and
+        # the surrounding transaction, so a capture failure aborts the ship and is
+        # reported back to ShipStation as an error (HTTP 400) rather than silently
+        # shipping an uncaptured order. ShipStation retries failed webhooks, so the
+        # operation is written to be safe to repeat: an already-shipped shipment is
+        # not re-shipped (see below) and capture only targets still-pending payments.
+        capture_pending_payments! if ::Spree::Config.auto_capture_on_dispatch
+
+        shipment.tracking = shipment_tracking
+        shipment.save!
+
+        shipment.ship! unless shipment.shipped?
+      end
+
+      def capture_pending_payments!
+        shipment.order.payments.pending.each do |payment|
+          payment.capture!
+        rescue ::Spree::Core::GatewayError
+          raise PaymentError.new(payment)
+        end
+      end
+    end
+  end
+end

data/lib/spree/shipstation/testing_support/factories/shipstation_integration.rb

@@ -0,0 +1,9 @@
+FactoryBot.define do
+  factory :shipstation_integration, class: Spree::Integrations::Shipstation do
+    active { true }
+    preferred_username { "myusernameisvalid23kd-ws" }
+    preferred_password { "aWc2yNoc27tLisYeT-J@4fjyDN6JZHj@2t-6YFXArFXNUsZBs-G-r" }
+
+    store { Spree::Store.default }
+  end
+end

data/lib/spree/shipstation/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Spree
+  module Shipstation
+    # Major version tracks Spree's major version: 5.x supports Spree 5.x.
+    VERSION = "5.0.0"
+
+    def self.version
+      Gem::Version.new(VERSION)
+    end
+  end
+end

data/lib/spree/shipstation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "pagy"
+
+require "spree_core"
+require "spree_extension"
+
+require "spree/shipstation/version"
+require "spree/shipstation/engine"
+require "spree/shipstation/errors"
+require "spree/shipstation/shipment_notice"

data/lib/spree-shipstation.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Bundler auto-requires a gem by its *name*, so `gem "spree-shipstation"` in a host
+# Gemfile issues `require "spree-shipstation"`. The gem's real entry point is
+# `spree/shipstation` (matching the Spree::Shipstation namespace), so this shim keeps
+# the default `Bundler.require` working without every consumer having to write
+# `gem "spree-shipstation", require: "spree/shipstation"`.
+require "spree/shipstation"