spree-shipstation 5.0.0 → 5.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30a88f9939731dc679980577dc0b23a91fdbda25c4019063b3f4728dfb2fe5a9
-  data.tar.gz: d410ae3a207dd0051ab938c3890c60c515b403723ac43392ede48ab872352ca1
+  metadata.gz: 59253a22e0dcd58163a5f9e3380f1e1c502f8256e05f7b2d65755b01a4879ec8
+  data.tar.gz: eb36256ce70cc0ab15858669bf823b4435f2a8d167a0517425af042db83dd95d
 SHA512:
-  metadata.gz: f1d456fbe2b2e4a682b7cc2b62e1c07faad779b449bd8f2da72e5a2ce67b9f133b8cb23a214bb62dfd2ba4d1429a6b1b6fc8839597feb3e445a31fd419de5869
-  data.tar.gz: ce40b12b11650ef36d848a709a4a0bd513c654a9ca6da8659728e178dd82cdba573504dbaf7ce981ef67509b986d0a11f47157f21280894dec8c90f2fae56769
+  metadata.gz: 4257f6418fa187a10b4f7b178f4b36d69516ba08d65d826260df6ff05056c9e63b176f97d61ae56c3645471f4868db03118f9d608d39eaed26d1d50bcce8dbad
+  data.tar.gz: 53537dda148d24860c62affd5b79f041bfce4431956b0a643e48cb3879229957a6ecad3476d5b6ae82b2d6ac6653b04d7f277345d39e0149bcdd5de0017d169f

data/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+---
+# Publishes to RubyGems.org via Trusted Publishing (OIDC) when a v* tag is
+# pushed. There is no API token or secret involved: GitHub mints a short-lived
+# identity token and RubyGems.org exchanges it for a push-scoped credential.
+#
+# Requires a trusted publisher registered on RubyGems.org for this gem with:
+#   owner       aypex-io
+#   repository  spree-shipstation
+#   workflow    release.yml
+#   environment release
+#
+# rubygems/release-gem runs `bundle exec rake release`. Bundler's GemHelper
+# skips tagging when the tag already exists, which it does here because the tag
+# push is what triggered the run.
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  push:
+    name: Push gem to RubyGems.org
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    # Must match the environment registered on the RubyGems trusted publisher.
+    environment: release
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # release-gem installs its own git credentials for the release task.
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ruby
+          bundler-cache: true
+
+      - uses: rubygems/release-gem@v1

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.0.1
+
+### Fixed
+
+- Export the correct `<Quantity>` for lines ordered more than once. Spree 5 stores
+  a quantity on each `Spree::InventoryUnit` rather than creating one unit row per
+  item, so counting rows reported every line as a quantity of 1 and ShipStation
+  under-picked multi-quantity orders. The quantity is now summed across the
+  line's inventory units, which also keeps a line split across shipments
+  reporting only the units in its own shipment.
+
 ## 5.0.0
 
 First public release on RubyGems, as `spree-shipstation`.

data/CLAUDE.md

@@ -50,6 +50,9 @@ bundle exec standardrb
 bundle exec standardrb --fix
 ```
 
+Public Ruby classes and methods use YARD `##` blocks. Specs follow one
+expectation per example.
+
 ## Architecture
 
 ### Integration Registration

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+m.kennedy@me.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 gem "appraisal"

data/README.md

@@ -118,3 +118,9 @@ bundle exec gem release
 ## License
 
 Copyright (c) 2021-2026 Matthew Kennedy, released under the MIT License.
+
+## Code of Conduct
+
+Everyone interacting in this project's codebases, issue trackers, and
+communication channels is expected to follow the [code of
+conduct](CODE_OF_CONDUCT.md).

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "bundler"
 Bundler::GemHelper.install_tasks
 

data/app/controllers/spree/shipstation_controller.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Spree
+  ##
+  # HTTP endpoints ShipStation polls for ready shipments and posts ship notices to.
+  #
   class ShipstationController < Spree::BaseController
     include Spree::IntegrationsHelper
     include Pagy::Method
@@ -10,6 +13,11 @@ module Spree
     before_action :ensure_active_integration
     before_action :authenticate_shipstation
 
+    ##
+    # XML export of ready shipments for ShipStation to pull.
+    #
+    # @return [void]
+    #
     def export
       @pagy, @shipments = pagy(
         current_store.shipments
@@ -24,6 +32,11 @@ module Spree
       end
     end
 
+    ##
+    # Applies a ship notification from ShipStation and marks the shipment shipped.
+    #
+    # @return [void]
+    #
     def shipnotify
       Shipstation::ShipmentNotice.from_payload(params.permit(:order_number, :tracking_number).to_h, store: current_store).apply
       head :ok

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

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

@@ -2,6 +2,9 @@
 
 module Spree
   module Integrations
+    ##
+    # Per-store ShipStation credentials registered with Spree's integration framework.
+    #
     class Shipstation < Spree::Integration
       preference :username, :string
 
@@ -45,14 +48,29 @@ module Spree
         },
         allow_blank: true
 
+      ##
+      # Admin grouping for this integration.
+      #
+      # @return [String]
+      #
       def self.integration_group
         "Shipping"
       end
 
+      ##
+      # Path to the logo shown in the admin integrations list.
+      #
+      # @return [String]
+      #
       def self.icon_path
         "integration_icons/shipstation-logo.webp"
       end
 
+      ##
+      # Translated brand name shown in the admin integrations list.
+      #
+      # @return [String]
+      #
       def self.integration_name
         Spree.t("admin.integrations.shipstation.brand_name")
       end

data/app/models/spree/shipment_decorator.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module Spree
+  ##
+  # Adds +exportable+ and +between+ scopes to +Spree::Shipment+ so the export
+  # endpoint can select ready shipments in a date window.
+  #
   module ShipmentDecorator
     def self.prepended(base)
       base.scope :exportable, lambda {

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

@@ -3,46 +3,85 @@
 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>.
+      # values ShipStation's export XML expects for an +<Item>+.
+      #
       class ItemPresenter
         attr_reader :line_item, :units
 
+        ##
+        # @param line_item [Spree::LineItem] the line item
+        # @param units [Array<Spree::InventoryUnit>] inventory units for that line
+        #
         def initialize(line_item, units)
           @line_item = line_item
           @units = units
         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::Image+ to advertise, or +nil+. URL generation stays in the
+        # view because it depends on Rails route/URL helpers.
+        #
+        # @return [Spree::Image, NilClass]
+        #
         def image
           variant.images.first || variant.product.master.images.first
         end
 
+        ##
+        # @return [Spree::Shipstation::Export::Weight]
+        #
         def weight
           Weight.from_variant(variant)
         end
 
+        ##
+        # The number of items to ship, summed across the line's inventory units.
+        #
+        # Spree stores a quantity on each +Spree::InventoryUnit+ rather than one
+        # row per item, so counting rows under-reports any line ordered more
+        # than once.
+        #
+        # @return [Integer]
+        #
         def quantity
-          units.size
+          units.sum(&:quantity)
         end
 
+        ##
+        # @return [BigDecimal]
+        #
         def unit_price
           line_item.price
         end
 
+        ##
+        # @return [ActiveRecord::Relation, Array]
+        #
         def option_values
           variant.option_values
         end

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

@@ -3,75 +3,131 @@
 module Spree
   module Shipstation
     module Export
-      # Shapes a single Spree::Shipment into the values ShipStation's export XML
+      ##
+      # 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).
+      # fields are derived from +shipment.order+ while identifiers come from the
+      # shipment itself (mirroring the +<OrderNumber>+ = shipment.number contract).
+      #
       class OrderPresenter
         attr_reader :shipment
 
+        ##
+        # @param shipment [Spree::Shipment] the shipment to export
+        #
         def initialize(shipment)
           @shipment = shipment
         end
 
+        ##
+        # @return [Spree::Order]
+        #
         def order
           shipment.order
         end
 
+        ##
+        # @return [Integer]
+        #
         def order_id
           shipment.id
         end
 
+        ##
+        # @return [String]
+        #
         def order_number
           shipment.number
         end
 
+        ##
+        # @return [String]
+        #
         def order_status
           shipment.state
         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)
         end
 
+        ##
+        # @return [String, NilClass]
+        #
         def shipping_method_name
           shipment.shipping_method&.name
         end
 
+        ##
+        # @return [BigDecimal]
+        #
         def order_total
           order.total
         end
 
+        ##
+        # @return [BigDecimal]
+        #
         def tax_total
           order.tax_total
         end
 
+        ##
+        # @return [BigDecimal]
+        #
         def ship_total
           order.ship_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.
+        #
+        # @return [Array<Spree::Shipstation::Export::ItemPresenter>]
+        #
         def items
           shipment.inventory_units.group_by(&:line_item).filter_map do |line_item, units|
             next unless line_item.variant

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

data/config/initializers/spree.rb

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

data/lib/spree/shipstation/engine.rb

@@ -2,6 +2,9 @@
 
 module Spree
   module Shipstation
+    ##
+    # Rails engine that loads decorator files and registers ShipStation assets.
+    #
     class Engine < ::Rails::Engine
       require "spree/core"
       isolate_namespace Spree

data/lib/spree/shipstation/errors.rb

@@ -2,20 +2,38 @@
 
 module Spree
   module Shipstation
+    ##
+    # Base error for ShipStation integration failures returned as HTTP 400.
+    #
     class Error < StandardError; end
 
+    ##
+    # Raised when the shipnotify payload names a shipment that does not exist.
+    #
     class ShipmentNotFoundError < Error
+      ##
+      # @param shipment_number [String] the shipment number from the payload
+      #
       def initialize(shipment_number, *args)
         super("Could not find shipment with number #{shipment_number}", *args)
       end
     end
 
+    ##
+    # Raised when a pending payment cannot be captured during shipnotify.
+    #
     class PaymentError < Error
+      ##
+      # @param payment [Spree::Payment] the payment that failed to capture
+      #
       def initialize(payment, *args)
         super("Could not process payment #{payment.id}", *args)
       end
     end
 
+    ##
+    # Raised when shipnotify is called without a tracking number.
+    #
     class MissingTrackingNumberError < Error
       def initialize(*args)
         super("Tracking number is required", *args)

data/lib/spree/shipstation/shipment_notice.rb

@@ -2,14 +2,31 @@
 
 module Spree
   module Shipstation
+    ##
+    # Applies a ShipStation shipnotify payload to a Spree shipment.
+    #
+    # Looks up the shipment by number on the given store and, inside a
+    # transaction: captures pending payments if +auto_capture_on_dispatch+ is
+    # on, writes the tracking number, and ships the shipment unless it is
+    # already shipped.
+    #
     class ShipmentNotice
       attr_reader :shipment_number, :shipment_tracking, :store
 
       class << self
+        ##
+        # Builds a notice from the shipnotify webhook params.
+        #
+        # ShipStation's webhook param is named +order_number+ but its value is
+        # the shipment number — it mirrors the +<OrderNumber>+ field from the
+        # export XML.
+        #
+        # @param params [Hash] webhook params including +:order_number+ and +:tracking_number+
+        # @param store [Spree::Store] store that owns the shipment
+        # @return [Spree::Shipstation::ShipmentNotice]
+        #
         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
@@ -17,12 +34,25 @@ module Spree
         end
       end
 
+      ##
+      # @param shipment_number [String] Spree shipment number
+      # @param shipment_tracking [String] carrier tracking number
+      # @param store [Spree::Store] store that owns the shipment
+      #
       def initialize(shipment_number:, shipment_tracking:, store:)
         @shipment_number = shipment_number
         @shipment_tracking = shipment_tracking
         @store = store
       end
 
+      ##
+      # Captures pending payments if configured, writes tracking, and ships.
+      #
+      # @return [Spree::Shipment] the updated shipment
+      # @raise [Spree::Shipstation::ShipmentNotFoundError] when the shipment is missing
+      # @raise [Spree::Shipstation::MissingTrackingNumberError] when tracking is blank
+      # @raise [Spree::Shipstation::PaymentError] when a pending payment cannot be captured
+      #
       def apply
         raise ShipmentNotFoundError, shipment_number unless shipment
 

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 FactoryBot.define do
   factory :shipstation_integration, class: Spree::Integrations::Shipstation do
     active { true }

data/lib/spree/shipstation/version.rb

@@ -3,8 +3,13 @@
 module Spree
   module Shipstation
     # Major version tracks Spree's major version: 5.x supports Spree 5.x.
-    VERSION = "5.0.0"
+    VERSION = "5.0.1"
 
+    ##
+    # Gem version as a comparable +Gem::Version+.
+    #
+    # @return [Gem::Version]
+    #
     def self.version
       Gem::Version.new(VERSION)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree-shipstation
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.0.1
 platform: ruby
 authors:
 - Matthew Kennedy
@@ -72,6 +72,7 @@ extra_rdoc_files: []
 files:
 - ".github/stale.yml"
 - ".github/workflows/lint.yml"
+- ".github/workflows/release.yml"
 - ".github/workflows/security.yml"
 - ".github/workflows/test.yml"
 - ".gitignore"
@@ -80,6 +81,7 @@ files:
 - Appraisals
 - CHANGELOG.md
 - CLAUDE.md
+- CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE
 - README.md
@@ -134,7 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.16
 specification_version: 4
 summary: ShipStation integration for Spree e-commerce
 test_files: []