spree-shipstation 5.0.1 → 6.0.0

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

@@ -6,6 +6,18 @@ module Spree
     # Per-store ShipStation credentials registered with Spree's integration framework.
     #
     class Shipstation < Spree::Integration
+      I18N_SCOPE = "spree.admin.integrations.shipstation"
+
+      # Password complexity rules, checked in order. Each key names the
+      # translation shown when its pattern does not match.
+      PASSWORD_RULES = {
+        must_contain_at_least_one_special_character: /[!@#$%^&*(),.?":{}|<>]/,
+        must_contain_at_least_one_uppercase_letter: /[A-Z]/,
+        must_contain_at_least_one_number: /\d/
+      }.freeze
+
+      LOGO_PATH = Spree::Shipstation::Engine.root.join("app/assets/images/integration_icons/shipstation-logo.webp")
+
       preference :username, :string
 
       validates :preferred_username,
@@ -17,7 +29,7 @@ module Spree
       validates :preferred_username,
         format: {
           with: /\A[a-zA-Z0-9._@+-]+\z/,
-          message: Spree.t("admin.integrations.shipstation.username_chars_error")
+          message: ->(_record, _data) { I18n.t("username_chars_error", scope: I18N_SCOPE) }
         },
         allow_blank: true
 
@@ -27,52 +39,61 @@ module Spree
         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
+      validate :password_complexity
 
       ##
-      # Admin grouping for this integration.
+      # Dashboard group key. Matches the group Spree's own shipping integrations use.
       #
       # @return [String]
       #
       def self.integration_group
-        "Shipping"
+        "shipping"
       end
 
       ##
-      # Path to the logo shown in the admin integrations list.
+      # Brand name shown in the dashboard's integrations list.
       #
       # @return [String]
       #
-      def self.icon_path
-        "integration_icons/shipstation-logo.webp"
+      def self.integration_name
+        I18n.t("brand_name", scope: I18N_SCOPE)
       end
 
       ##
-      # Translated brand name shown in the admin integrations list.
+      # The bundled logo as a +data:+ URI, so the dashboard can render it with
+      # no asset pipeline and no hosted file. Read once, then memoised.
       #
       # @return [String]
       #
-      def self.integration_name
-        Spree.t("admin.integrations.shipstation.brand_name")
+      def self.logo_url
+        # Array#pack("m0") is strict Base64 without the base64 gem, which
+        # Ruby 3.4 and later no longer ship as a default gem.
+        @logo_url ||= "data:image/webp;base64,#{[LOGO_PATH.binread].pack("m0")}".freeze
+      end
+
+      ##
+      # Link to this extension's setup guide, shown on the dashboard's gallery card.
+      #
+      # @return [String]
+      #
+      def self.docs_url
+        "https://github.com/aypex-io/spree-shipstation#readme"
+      end
+
+      private
+
+      # Adds an error for each complexity rule the password fails. Written as a
+      # method rather than three +format:+ validations because those patterns
+      # are deliberately unanchored ("contains"), which Brakeman flags.
+      def password_complexity
+        password = preferred_password
+        return if password.blank?
+
+        PASSWORD_RULES.each do |message_key, pattern|
+          next if pattern.match?(password)
+
+          errors.add(:preferred_password, I18n.t(message_key, scope: I18N_SCOPE))
+        end
       end
     end
   end

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

@@ -4,19 +4,20 @@ 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>+.
+      # Shapes a parcel's line item (a line item plus its fulfillment items) into
+      # the values ShipStation's export XML expects for an +<Item>+.
       #
       class ItemPresenter
-        attr_reader :line_item, :units
+        attr_reader :line_item, :fulfillment_items
 
         ##
         # @param line_item [Spree::LineItem] the line item
-        # @param units [Array<Spree::InventoryUnit>] inventory units for that line
+        # @param fulfillment_items [Array<Spree::FulfillmentItem>] the parcel's
+        #   fulfillment items for that line
         #
-        def initialize(line_item, units)
+        def initialize(line_item, fulfillment_items)
           @line_item = line_item
-          @units = units
+          @fulfillment_items = fulfillment_items
         end
 
         ##
@@ -43,13 +44,14 @@ module Spree
         end
 
         ##
-        # The +Spree::Image+ to advertise, or +nil+. URL generation stays in the
-        # view because it depends on Rails route/URL helpers.
+        # The +Spree::Media+ to advertise, or +nil+: the variant's primary media,
+        # else its product's. URL generation stays in the view because it depends
+        # on Rails route/URL helpers.
         #
-        # @return [Spree::Image, NilClass]
+        # @return [Spree::Media, NilClass]
         #
         def image
-          variant.images.first || variant.product.master.images.first
+          variant.thumbnail
         end
 
         ##
@@ -60,16 +62,16 @@ module Spree
         end
 
         ##
-        # The number of items to ship, summed across the line's inventory units.
+        # The number of items to ship, summed across the line's fulfillment items.
         #
-        # Spree stores a quantity on each +Spree::InventoryUnit+ rather than one
+        # Spree stores a quantity on each +Spree::FulfillmentItem+ rather than one
         # row per item, so counting rows under-reports any line ordered more
         # than once.
         #
         # @return [Integer]
         #
         def quantity
-          units.sum(&:quantity)
+          fulfillment_items.sum(&:quantity)
         end
 
         ##
@@ -80,10 +82,13 @@ module Spree
         end
 
         ##
-        # @return [ActiveRecord::Relation, Array]
+        # The variant's options as pairs of the option type's label and the
+        # option value's name, which is how ShipStation lists them.
+        #
+        # @return [Array<Array(String, String)>]
         #
         def option_values
-          variant.option_values
+          variant.option_values.map { |value| [value.option_type.label, value.name] }
         end
       end
     end

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

@@ -4,49 +4,58 @@ 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.
+      # Shapes a single +Spree::Fulfillment+ (a parcel) 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).
+      # Note: ShipStation models one "Order" per parcel, so most order-level
+      # fields are derived from +fulfillment.order+ while identifiers come from
+      # the fulfillment itself (mirroring the +<OrderNumber>+ = fulfillment.number
+      # contract).
       #
       class OrderPresenter
-        attr_reader :shipment
+        attr_reader :fulfillment
 
         ##
-        # @param shipment [Spree::Shipment] the shipment to export
+        # @param fulfillment [Spree::Fulfillment] the parcel to export
         #
-        def initialize(shipment)
-          @shipment = shipment
+        def initialize(fulfillment)
+          @fulfillment = fulfillment
         end
 
         ##
         # @return [Spree::Order]
         #
         def order
-          shipment.order
+          fulfillment.order
         end
 
         ##
         # @return [Integer]
         #
         def order_id
-          shipment.id
+          fulfillment.id
         end
 
         ##
+        # The number ShipStation echoes back in the ship notice: the stored number
+        # of a parcel created before Spree 6.0, otherwise one derived from its
+        # order, such as +R1001-F1+.
+        #
         # @return [String]
         #
         def order_number
-          shipment.number
+          fulfillment.number
         end
 
         ##
+        # Always +ready+. The export only offers parcels that can ship now, and
+        # merchants' ShipStation status mappings key on this value.
+        #
         # @return [String]
         #
         def order_status
-          shipment.state
+          "ready"
         end
 
         ##
@@ -60,14 +69,16 @@ module Spree
         # @return [String, NilClass]
         #
         def last_modified
-          format_date([order.completed_at, shipment.updated_at].compact.max)
+          format_date([order.completed_at, fulfillment.updated_at].compact.max)
         end
 
         ##
+        # The name of the delivery method selected for the parcel.
+        #
         # @return [String, NilClass]
         #
         def shipping_method_name
-          shipment.shipping_method&.name
+          fulfillment.delivery_method&.name
         end
 
         ##
@@ -85,10 +96,12 @@ module Spree
         end
 
         ##
+        # The order's delivery charge, exported as ShipStation's ShippingAmount.
+        #
         # @return [BigDecimal]
         #
         def ship_total
-          order.ship_total
+          order.delivery_total
         end
 
         ##
@@ -124,15 +137,16 @@ module Spree
         end
 
         ##
-        # One presenter per line item that still has a variant.
+        # One presenter per line item that still has a variant, built from the
+        # parcel's fulfillment items for that line.
         #
         # @return [Array<Spree::Shipstation::Export::ItemPresenter>]
         #
         def items
-          shipment.inventory_units.group_by(&:line_item).filter_map do |line_item, units|
+          fulfillment.fulfillment_items.group_by(&:line_item).filter_map do |line_item, fulfillment_items|
             next unless line_item.variant
 
-            ItemPresenter.new(line_item, units)
+            ItemPresenter.new(line_item, fulfillment_items)
           end
         end
 

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

@@ -1,8 +1,8 @@
 xml.instruct!
 
 xml.Orders(pages: @pagy.pages) do
-  @shipments.each do |shipment|
-    order = Spree::Shipstation::Export::OrderPresenter.new(shipment)
+  @fulfillments.each do |fulfillment|
+    order = Spree::Shipstation::Export::OrderPresenter.new(fulfillment)
 
     xml.Order do
       xml.OrderID order.order_id
@@ -27,13 +27,15 @@ xml.Orders(pages: @pagy.pages) do
       xml.Items do
         order.items.each do |item|
           weight = item.weight
-          image = item.image
+          # The thumbnail may be a video. Its still image is the poster, and is
+          # nil for an embedded video, which has no attachment to link to.
+          still_image = item.image&.still_image
 
           xml.Item do
             xml.SKU item.sku
             xml.Name item.name
 
-            image_url = image && url_for(image.attachment)
+            image_url = still_image && url_for(still_image)
             xml.ImageUrl image_url if image_url
 
             xml.Weight weight.value
@@ -43,10 +45,10 @@ xml.Orders(pages: @pagy.pages) do
 
             if item.option_values.present?
               xml.Options do
-                item.option_values.each do |value|
+                item.option_values.each do |name, value|
                   xml.Option do
-                    xml.Name value.option_type.presentation
-                    xml.Value value.name
+                    xml.Name name
+                    xml.Value value
                   end
                 end
               end

data/config/initializers/spree.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Spree resolves registered entries to classes itself, so the class name string
+# avoids loading the model before the app has finished booting.
 Rails.application.config.after_initialize do
-  Rails.application.config.spree.integrations << Spree::Integrations::Shipstation
+  Spree.integrations << "Spree::Integrations::Shipstation"
 end

data/config/locales/en.yml

@@ -1,15 +1,14 @@
 ---
 en:
   spree:
+    integrations:
+      shipstation:
+        description: Integrate with ShipStation to automate your shipping workflows from a single dashboard.
     admin:
       integrations:
         shipstation:
+          brand_name: 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

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
+# ShipStation pulls orders and posts ship notices to the same URL. The bare path
+# belongs to the default store. The path that names an integration (its prefixed
+# id) belongs to that integration's store, which is how a second store gets an
+# endpoint of its own.
+#
+# The export is XML whether or not the URL ends in +.xml+. Without the default,
+# a pull that sends a browser-like Accept header would be refused with a 406.
 Spree::Core::Engine.add_routes do
-  get "/shipstation", to: "shipstation#export"
-  post "/shipstation", to: "shipstation#shipnotify"
+  get "/shipstation(.:format)", to: "shipstation#export", defaults: {format: "xml"}
+  post "/shipstation(.:format)", to: "shipstation#shipnotify"
+
+  get "/shipstation/:integration_id(.:format)", to: "shipstation#export", defaults: {format: "xml"}
+  post "/shipstation/:integration_id(.:format)", to: "shipstation#shipnotify"
 end

data/lib/spree/shipstation/engine.rb

@@ -3,7 +3,8 @@
 module Spree
   module Shipstation
     ##
-    # Rails engine that loads decorator files and registers ShipStation assets.
+    # Rails engine for the ShipStation integration. It makes the gem's +app+ and
+    # +config+ directories part of the host application.
     #
     class Engine < ::Rails::Engine
       require "spree/core"
@@ -17,19 +18,6 @@ module Spree
       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

@@ -20,14 +20,46 @@ module Spree
     end
 
     ##
-    # Raised when a pending payment cannot be captured during shipnotify.
+    # Raised when the ship notice's +OrderID+ names a fulfillment of a different
+    # order from the one its order number names.
+    #
+    class ShipmentMismatchError < Error
+      ##
+      # @param shipment_number [String] the order number from the notice
+      # @param shipment_id [Integer] the +OrderID+ from the notice
+      #
+      def initialize(shipment_number, shipment_id, *args)
+        super("Shipment #{shipment_number} does not match order id #{shipment_id}", *args)
+      end
+    end
+
+    ##
+    # Raised when the shipnotify payload names a shipment Spree has canceled.
+    #
+    class FulfillmentCanceledError < Error
+      ##
+      # @param shipment_number [String] the number of the canceled shipment
+      #
+      def initialize(shipment_number, *args)
+        super("Shipment #{shipment_number} is canceled", *args)
+      end
+    end
+
+    ##
+    # Raised when Spree refuses to fulfil the shipment, for instance because the
+    # order is not paid or holds backordered items. The message is Spree's own.
+    #
+    class FulfillmentRefusedError < Error; end
+
+    ##
+    # Raised when a payment cannot be captured during shipnotify.
     #
     class PaymentError < Error
       ##
-      # @param payment [Spree::Payment] the payment that failed to capture
+      # @param message [String] why the capture failed, as the gateway reported it
       #
-      def initialize(payment, *args)
-        super("Could not process payment #{payment.id}", *args)
+      def initialize(message, *args)
+        super("Could not capture payment: #{message}", *args)
       end
     end
 

data/lib/spree/shipstation/export_query.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Spree
+  module Shipstation
+    ##
+    # Selects the parcels ShipStation should pull: the store's fulfillments that
+    # Spree will let ship right now.
+    #
+    # Spree 6 keeps no "ready" status. A fulfillment is +unfulfilled+ until
+    # someone hands it over, and whether it can go out is decided when it is
+    # fulfilled. This query asks the same questions ahead of time, so ShipStation
+    # is not offered parcels that Spree would refuse at the ship notice. A parcel
+    # is exported when all of these hold:
+    #
+    # * it is one of the store's fulfillments and is still +unfulfilled+;
+    # * its order is placed, which leaves out drafts and canceled orders;
+    # * its order is paid: +paid+, +overcharged+ or +partially_refunded+, or it
+    #   owes nothing (+total = 0+, whose payment status stays +none+), or, on a
+    #   store that captures on dispatch or manually, it is +authorized+ or
+    #   +partially_paid+ (mixed tender: store credit captured at checkout, say,
+    #   and a card authorized for the rest). A payment method that overrides
+    #   the store's setting is not consulted;
+    # * none of its items is backordered;
+    # * its selected delivery method is not a pickup or a pickup point.
+    #
+    # These are most of Spree's fulfil checks, not all of them, so the ship
+    # notice may still be refused, with Spree's reason. Spree also checks, when
+    # the parcel is fulfilled, that the stock location has the units on hand,
+    # and it compares the net captured amount (net of refunds) with what was
+    # due: a partially refunded order is exported but may fall short, and a
+    # partially paid one ships only while the rest is authorized on payment
+    # methods that defer capture.
+    #
+    # @example
+    #   Spree::Shipstation::ExportQuery.new(store: store, from: 1.day.ago).call
+    #
+    class ExportQuery
+      PAID_STATUSES = %w[paid overcharged partially_refunded].freeze
+      private_constant :PAID_STATUSES
+
+      # Shippable as well when the store captures on dispatch or manually.
+      DEFERRED_CAPTURE_STATUSES = %w[authorized partially_paid].freeze
+      private_constant :DEFERRED_CAPTURE_STATUSES
+
+      PRELOADS = {
+        order: [:bill_address, :ship_address, :fulfillments],
+        selected_delivery_rate: :delivery_method,
+        fulfillment_items: {
+          line_item: {
+            variant: [{product: :primary_media}, :primary_media, {option_values: :option_type}]
+          }
+        }
+      }.freeze
+      private_constant :PRELOADS
+
+      ##
+      # @param store [Spree::Store] the store whose fulfillments are exported
+      # @param from [Time, NilClass] start of the date window
+      # @param to [Time, NilClass] end of the date window
+      #
+      def initialize(store:, from: nil, to: nil)
+        @store = store
+        @from = from
+        @to = to
+      end
+
+      ##
+      # The exportable parcels, oldest update first, with everything the export
+      # presenters read already loaded.
+      #
+      # A parcel falls in the window when its own +updated_at+ or its order's does.
+      # With neither +from+ nor +to+ there is no window, and with only one of them
+      # the window is open-ended.
+      #
+      # @return [ActiveRecord::Relation<Spree::Fulfillment>]
+      #
+      def call
+        within_window(shippable)
+          .reorder(updated_at: :asc, id: :asc)
+          .preload(PRELOADS)
+      end
+
+      private
+
+      attr_reader :store, :from, :to
+
+      def shippable
+        store.fulfillments
+          .unfulfilled
+          .merge(Spree::Order.placed_orders)
+          .merge(paid_orders)
+          .where.not(id: backordered_fulfillment_ids)
+          .where.not(id: pickup_fulfillment_ids)
+      end
+
+      # A free order's payment status stays +none+, but Spree ships it.
+      def paid_orders
+        Spree::Order.where(payment_status: paid_statuses).or(Spree::Order.where(total: 0))
+      end
+
+      # An order that is authorized, in full or for the part not captured at
+      # checkout, can ship when the store charges it at dispatch or leaves it to
+      # staff: Spree lets it through when every pending payment defers capture.
+      # On a store that captures at checkout, authorized money is not yet paid.
+      def paid_statuses
+        store.capture_at_checkout? ? PAID_STATUSES : PAID_STATUSES + DEFERRED_CAPTURE_STATUSES
+      end
+
+      # The +fulfillment_id IS NOT NULL+ guards matter: a single NULL in a +NOT IN+
+      # list makes the comparison unknown for every row, which would export nothing.
+      def backordered_fulfillment_ids
+        Spree::FulfillmentItem.backordered.where.not(fulfillment_id: nil).select(:fulfillment_id)
+      end
+
+      # Only the delivery method the customer chose counts. A parcel may carry a
+      # pickup rate among the options it was offered. Methods are read with
+      # deleted ones, since orders outlive the method they were placed with.
+      def pickup_fulfillment_ids
+        pickups = Spree::DeliveryMethod.with_deleted.with_provider(:pickup?)
+          .or(Spree::DeliveryMethod.with_deleted.with_provider(:pickup_point?))
+
+        Spree::DeliveryRate
+          .where(selected: true, delivery_method_id: pickups.select(:id))
+          .where.not(fulfillment_id: nil)
+          .select(:fulfillment_id)
+      end
+
+      def within_window(scope)
+        return scope if from.nil? && to.nil?
+
+        window = from..to
+        scope.where(updated_at: window).or(scope.where(Spree::Order.table_name => {updated_at: window}))
+      end
+    end
+  end
+end