spree-shipstation 5.0.0 → 6.0.0

data/app/controllers/spree/shipstation_controller.rb

@@ -1,31 +1,68 @@
 # frozen_string_literal: true
 
 module Spree
-  class ShipstationController < Spree::BaseController
-    include Spree::IntegrationsHelper
+  ##
+  # HTTP endpoints ShipStation polls for ready parcels and posts ship notices to.
+  #
+  # Every request is answered for one ShipStation integration, and so for one
+  # store. The bare +/shipstation+ path uses the default store's integration;
+  # +/shipstation/:integration_id+ uses the integration with that prefixed id.
+  # Requests are authenticated with HTTP Basic against the integration's own
+  # credentials, after the integration is found: with no active integration the
+  # answer is 404, whoever asks.
+  #
+  # This is an +ActionController::Base+ rather than an API controller because
+  # the export is a Builder template, which +ActionController::API+ renders as
+  # an empty body.
+  #
+  class ShipstationController < ActionController::Base
+    include Spree::Core::ControllerHelpers::Store
     include Pagy::Method
 
-    protect_from_forgery with: :null_session, only: :shipnotify
+    PER_PAGE = 50
+    private_constant :PER_PAGE
 
-    before_action :ensure_active_integration
+    # A ship notice body is a few kilobytes. A larger one is not parsed.
+    MAX_NOTICE_BYTES = 64.kilobytes
+    private_constant :MAX_NOTICE_BYTES
+
+    # Forgery protection is the default for this controller, so an action added
+    # later is protected until it says otherwise. ShipStation's two actions opt
+    # out: HTTP Basic is their authentication and there is no session to forge.
+    protect_from_forgery with: :exception
+    skip_forgery_protection only: %i[export shipnotify]
+
+    before_action :find_integration
     before_action :authenticate_shipstation
 
+    ##
+    # XML export of the store's ready parcels for ShipStation to pull.
+    #
+    # @return [void]
+    #
     def export
-      @pagy, @shipments = pagy(
-        current_store.shipments
-          .exportable
-          .between(date_param(:start_date), date_param(:end_date)),
-        page: params[:page],
-        items: 50
+      query = Shipstation::ExportQuery.new(
+        store: @integration.store,
+        from: date_param(:start_date),
+        to: date_param(:end_date)
       )
+      @pagy, @fulfillments = pagy(query.call, limit: PER_PAGE)
 
       respond_to do |format|
         format.xml { render layout: false }
       end
     end
 
+    ##
+    # Applies a ship notice from ShipStation and fulfils the parcel. The notice
+    # travels in the query string. Of the XML body ShipStation also sends, only
+    # the +OrderID+ is read.
+    #
+    # @return [void]
+    #
     def shipnotify
-      Shipstation::ShipmentNotice.from_payload(params.permit(:order_number, :tracking_number).to_h, store: current_store).apply
+      payload = notice_params.merge(order_id: notice_order_id)
+      Shipstation::ShipmentNotice.from_payload(payload, store: @integration.store).apply
       head :ok
     rescue Shipstation::Error => e
       Rails.logger.error("ShipStation Notification Error: #{e.message}")
@@ -34,10 +71,52 @@ module Spree
 
     private
 
-    def ensure_active_integration
-      head :not_found unless store_integration("shipstation")&.active?
+    # Only the notice's own fields. Sliced first, so the integration id, the
+    # format and ShipStation's other query params are never "unpermitted", which
+    # would raise in a host app that treats them so.
+    def notice_params
+      params.slice(:order_number, :tracking_number, :carrier)
+        .permit(:order_number, :tracking_number, :carrier).to_h
+    end
+
+    # The +OrderID+ from the notice's XML body: the fulfillment's id, as the
+    # export sent it. Parsed strictly and with Nokogiri's defaults otherwise, so
+    # no network access and no entity expansion. A body that is empty, too
+    # large or not well-formed, or an +OrderID+ that is missing or not a whole
+    # number, gives nil, and the notice is matched on its number alone.
+    def notice_order_id
+      body = request.raw_post
+      return if body.blank? || body.bytesize > MAX_NOTICE_BYTES
+
+      text = Nokogiri::XML(body, &:strict).at_xpath("/ShipNotice/OrderID")&.text.to_s.strip
+      text.to_i if text.match?(/\A\d+\z/)
+    rescue Nokogiri::XML::SyntaxError
+      nil
+    end
+
+    # Finds the active integration this request is for and makes its store the
+    # current one. Anything else is a 404, before the caller is asked who they are.
+    def find_integration
+      @integration = resolve_integration
+      return head :not_found unless @integration
+
+      Spree::Current.store = @integration.store
     end
 
+    # Only the path names an integration. A query-string +integration_id+ on the
+    # bare URL is ignored, so that URL always belongs to the default store.
+    def resolve_integration
+      integration_id = request.path_parameters[:integration_id]
+
+      if integration_id.present?
+        Spree::Integrations::Shipstation.active.find_by_prefix_id(integration_id)
+      else
+        current_store.integrations.active.find_by(type: Spree::Integrations::Shipstation.sti_name)
+      end
+    end
+
+    # ShipStation sends dates as +MM/DD/YYYY HH:MM+ in UTC. One it cannot read
+    # is dropped, which widens the window rather than failing the pull.
     def date_param(name)
       return if params[name].blank?
 
@@ -48,9 +127,13 @@ module Spree
 
     def authenticate_shipstation
       authenticate_or_request_with_http_basic do |username, password|
-        integration = store_integration("shipstation")
-        ActiveSupport::SecurityUtils.secure_compare(username.to_s, integration.preferred_username.to_s) &&
-          ActiveSupport::SecurityUtils.secure_compare(password.to_s, integration.preferred_password.to_s)
+        # Credentials the integration does not hold would match anything blank.
+        next false if @integration.preferred_username.blank? || @integration.preferred_password.blank?
+
+        # A non-short-circuiting & so both fields are always compared, and the
+        # time taken does not reveal whether the username matched.
+        ActiveSupport::SecurityUtils.secure_compare(username.to_s, @integration.preferred_username.to_s) &
+          ActiveSupport::SecurityUtils.secure_compare(password.to_s, @integration.preferred_password.to_s)
       end
     end
   end

data/app/helpers/spree/shipstation/export_helper.rb

@@ -4,13 +4,30 @@ require "builder"
 
 module Spree
   module Shipstation
+    ##
+    # Builds ShipStation address XML nodes for the export template.
+    #
     module ExportHelper
       DATE_FORMAT = "%m/%d/%Y %H:%M"
 
+      ##
+      # Emits a +BillTo+ node without street-level fields.
+      #
+      # @param xml [Builder::XmlMarkup] the XML builder
+      # @param address [Spree::Address, NilClass] billing address
+      # @return [String, NilClass]
+      #
       def self.bill_address(xml, address)
         render_address(xml, address, "BillTo", include_street: false)
       end
 
+      ##
+      # Emits a +ShipTo+ node including street-level fields.
+      #
+      # @param xml [Builder::XmlMarkup] the XML builder
+      # @param address [Spree::Address, NilClass] shipping address
+      # @return [String, NilClass]
+      #
       def self.ship_address(xml, address)
         render_address(xml, address, "ShipTo", include_street: true)
       end
@@ -22,7 +39,7 @@ module Spree
           return unless address
 
           xml.tag!(tag_name) do
-            xml.Name name_from(address)
+            xml.Name address.full_name
             xml.Company address.company
 
             if include_street
@@ -30,22 +47,16 @@ module Spree
               xml.Address2 address.address2
               xml.City address.city
               xml.State state_from(address)
-              xml.PostalCode address.zipcode
-              xml.Country address.country&.iso
+              xml.PostalCode address.postal_code
+              xml.Country address.country_code
             end
 
             xml.Phone address.phone
           end
         end
 
-        def name_from(address)
-          return address.name if address.respond_to?(:name)
-
-          address.try(:full_name)
-        end
-
         def state_from(address)
-          address.state&.abbr || address.state_name
+          address.state_code.presence || address.state_name
         end
       end
     end

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

@@ -2,7 +2,22 @@
 
 module Spree
   module Integrations
+    ##
+    # 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,
@@ -14,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
 
@@ -24,37 +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
+      validate :password_complexity
 
-      validates :preferred_password,
-        format: {
-          with: /[A-Z]/,
-          message: Spree.t("admin.integrations.shipstation.must_contain_at_least_one_uppercase_letter")
-        },
-        allow_blank: true
+      ##
+      # Dashboard group key. Matches the group Spree's own shipping integrations use.
+      #
+      # @return [String]
+      #
+      def self.integration_group
+        "shipping"
+      end
 
-      validates :preferred_password,
-        format: {
-          with: /\d/,
-          message: Spree.t("admin.integrations.shipstation.must_contain_at_least_one_number")
-        },
-        allow_blank: true
+      ##
+      # Brand name shown in the dashboard's integrations list.
+      #
+      # @return [String]
+      #
+      def self.integration_name
+        I18n.t("brand_name", scope: I18N_SCOPE)
+      end
 
-      def self.integration_group
-        "Shipping"
+      ##
+      # 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.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
 
-      def self.icon_path
-        "integration_icons/shipstation-logo.webp"
+      ##
+      # 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
 
-      def self.integration_name
-        Spree.t("admin.integrations.shipstation.brand_name")
+      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

@@ -3,48 +3,92 @@
 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
 
-        def initialize(line_item, units)
+        ##
+        # @param line_item [Spree::LineItem] the line item
+        # @param fulfillment_items [Array<Spree::FulfillmentItem>] the parcel's
+        #   fulfillment items for that line
+        #
+        def initialize(line_item, fulfillment_items)
           @line_item = line_item
-          @units = units
+          @fulfillment_items = fulfillment_items
         end
 
+        ##
+        # @return [Spree::Variant]
+        #
         def variant
           @variant ||= line_item.variant
         end
 
+        ##
+        # @return [String]
+        #
         def sku
           variant.sku
         end
 
+        ##
+        # Product name plus variant options, dropping blanks.
+        #
+        # @return [String]
+        #
         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.
+        ##
+        # 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::Media, NilClass]
+        #
         def image
-          variant.images.first || variant.product.master.images.first
+          variant.thumbnail
         end
 
+        ##
+        # @return [Spree::Shipstation::Export::Weight]
+        #
         def weight
           Weight.from_variant(variant)
         end
 
+        ##
+        # The number of items to ship, summed across the line's fulfillment items.
+        #
+        # 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.size
+          fulfillment_items.sum(&:quantity)
         end
 
+        ##
+        # @return [BigDecimal]
+        #
         def unit_price
           line_item.price
         end
 
+        ##
+        # 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

@@ -3,80 +3,150 @@
 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 parcel, so most order-level
+      # fields are derived from +fulfillment.order+ while identifiers come from
+      # the fulfillment itself (mirroring the +<OrderNumber>+ = fulfillment.number
+      # contract).
       #
-      # 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
+        attr_reader :fulfillment
 
-        def initialize(shipment)
-          @shipment = shipment
+        ##
+        # @param fulfillment [Spree::Fulfillment] the parcel to export
+        #
+        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
 
+        ##
+        # @return [String, NilClass]
+        #
         def order_date
           format_date(order.completed_at)
         end
 
+        ##
+        # @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
 
+        ##
+        # @return [BigDecimal]
+        #
         def order_total
           order.total
         end
 
+        ##
+        # @return [BigDecimal]
+        #
         def tax_total
           order.tax_total
         end
 
+        ##
+        # The order's delivery charge, exported as ShipStation's ShippingAmount.
+        #
+        # @return [BigDecimal]
+        #
         def ship_total
-          order.ship_total
+          order.delivery_total
         end
 
+        ##
+        # Spree order number, exported as ShipStation CustomField1.
+        #
+        # @return [String]
+        #
         def custom_field_1
           order.number
         end
 
+        ##
+        # Email truncated to ShipStation's 50-character customer-code limit.
+        #
+        # @return [String, NilClass]
+        #
         def customer_code
           order.email&.slice(0, 50)
         end
 
+        ##
+        # @return [Spree::Address, NilClass]
+        #
         def bill_address
           order.bill_address
         end
 
+        ##
+        # @return [Spree::Address, NilClass]
+        #
         def ship_address
           order.ship_address
         end
 
+        ##
+        # 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/presenters/spree/shipstation/export/weight.rb

@@ -3,19 +3,31 @@
 module Spree
   module Shipstation
     module Export
-      # Value object converting a Spree::Variant's weight into the
+      ##
+      # 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
 
+        ##
+        # @param value [Float] numeric weight
+        # @param units [String] ShipStation unit label
+        #
         def initialize(value:, units:)
           @value = value
           @units = units
         end
 
+        ##
+        # Converts a variant's weight into ShipStation units.
+        #
+        # @param variant [Spree::Variant]
+        # @return [Spree::Shipstation::Export::Weight]
+        #
         def self.from_variant(variant)
           amount = (variant.weight || 0.0).to_f
 
@@ -31,11 +43,18 @@ module Spree
           end
         end
 
+        ##
+        # @param other [Object]
+        # @return [TrueClass, FalseClass]
+        #
         def ==(other)
           other.is_a?(self.class) && value == other.value && units == other.units
         end
         alias_method :eql?, :==
 
+        ##
+        # @return [Integer]
+        #
         def hash
           [value, units].hash
         end