spree-shipstation 5.0.1 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59253a22e0dcd58163a5f9e3380f1e1c502f8256e05f7b2d65755b01a4879ec8
-  data.tar.gz: eb36256ce70cc0ab15858669bf823b4435f2a8d167a0517425af042db83dd95d
+  metadata.gz: 1ec0ccf29f471fcbd60126248195ed5adbb10f9ae5cc5301b23b640308ce6f0f
+  data.tar.gz: 97d83306702cbbac6b67f7d4e2bca35676063e397e7e13717ad4eaed7e0d3487
 SHA512:
-  metadata.gz: 4257f6418fa187a10b4f7b178f4b36d69516ba08d65d826260df6ff05056c9e63b176f97d61ae56c3645471f4868db03118f9d608d39eaed26d1d50bcce8dbad
-  data.tar.gz: 53537dda148d24860c62affd5b79f041bfce4431956b0a643e48cb3879229957a6ecad3476d5b6ae82b2d6ac6653b04d7f277345d39e0149bcdd5de0017d169f
+  metadata.gz: 80e0b2aa61bcc31c1a59249d02522b548899cdea0fa5a7dfb04ba03aa24916105c54434495095f598a54a5d8aa472f58be1cfd2a9eb8c48636efcc8f759eaa84
+  data.tar.gz: c3650585bc19e8dd5d89571771b413fa64de828a9f82afd72a899cbb0f751d576367dc8de94bd5d2f18b8e267da6ea84b37cd32a069aa1b12bed3999f530a26f

data/.gitignore

@@ -19,5 +19,4 @@ spec/dummy
 public/spree
 .ruby-version
 .ruby-gemset
-gemfiles/*.gemfile.lock
 *.gem

data/CHANGELOG.md

@@ -2,6 +2,121 @@
 
 All notable changes to this project are documented in this file.
 
+## 6.0.0
+
+Spree 6 support. The major version tracks Spree's, so `spree-shipstation` 6.x
+supports Spree 6, and Spree 5 stays on the 5.0.x releases (the `5-0-stable`
+branch).
+
+**Nothing ShipStation or the merchant has configured has to change** for the
+default store. The `/shipstation` URL, the credentials, the XML, the `ready`
+status and the `OrderNumber` of every fulfillment ShipStation already holds stay
+as they were. A store other than the default moves to its integration's URL
+(below).
+
+**Run `bin/rake spree:upgrade` right after `db:migrate`, before ShipStation next
+polls.** Spree's upgrade tasks move 5.x shipment statuses to fulfillment statuses
+(`ready` and `pending` become `unfulfilled`, `shipped` becomes `fulfilled`),
+backfill the delivery-method providers the pickup rule reads, recompute the
+statuses of orders whose shipments were pending, ready or shipped, encrypt stored
+secrets, and carry `auto_capture_on_dispatch` over to the store's
+`capture_method`. Until then the export is empty. See "Upgrading
+from 5.0" in the README.
+
+**Requirements:** Spree `~> 6.0`, Ruby 3.3 or newer, pagy 43.6 or newer. The 5.x
+releases do not install on Spree 6.
+
+### Changed
+
+- **Orders are exported per fulfillment**, since Spree 6 replaced shipments with
+  fulfillments. `OrderID` is the fulfillment's id and `OrderNumber` its number:
+  the number a fulfillment already had before Spree 6, or `R1001-F1` style
+  (order number, `-F`, position) for new ones. Totals stay order-level, as before.
+- **Only fulfillments Spree will let ship are exported**: placed, still
+  unfulfilled, paid, with nothing backordered, and not a pickup. "Paid" means
+  paid, overcharged or partially refunded; or nothing owed; or, on a store whose
+  capture method is `on_dispatch` or `manual`, authorized, or partially paid with
+  the rest authorized (mixed tender, such as store credit plus a card). As before,
+  unpaid or backordered fulfillments do not appear in ShipStation until they can
+  ship: 5.x exported only `ready` shipments. Results are ordered by last update,
+  oldest first.
+- **Ship notices fulfil through Spree 6's fulfil workflow.** When Spree refuses
+  (an unpaid order, backordered items, a canceled fulfillment) the notice is
+  answered with `400` and Spree's reason, and nothing is recorded. It is never
+  answered `200` for a fulfillment Spree did not ship.
+- **Ship notices are retry-safe.** A notice for a fulfillment that is already
+  fulfilled or delivered only records or corrects the tracking number: it does
+  not fulfil the parcel or publish the event again. A retry that names a tracking
+  number already on another delivery of the same fulfillment is refused with
+  `400` ("Tracking number has already been taken"). Concurrent retries are
+  serialized under the order's row lock. A parcel still marked `shipped` from 5.x,
+  before Spree's upgrade task renames the status, is treated the same way.
+- **A notice without an order number is refused** with `400`. New fulfillments
+  store no number, so a blank one would otherwise match any of them.
+- **Capture on dispatch follows Spree 6's `capture_method`**, set on the store or
+  overridden per payment method. A declined capture answers `400` ("Could not
+  capture payment: ...") and keeps nothing: the fulfillment stays unfulfilled,
+  the payment stays pending and the tracking written during the attempt is rolled
+  back, so the retry starts from the same place.
+- **Shipped notifications are the host app's to send.** Spree 6 core sends no
+  shipped email itself. The fulfil workflow publishes `fulfillment.fulfilled` with
+  `notify_customer` set, and your application's subscriber decides whether, and
+  how, to tell the customer. On a declined capture core publishes that event
+  inside the transaction that is then rolled back, so a subscriber that notifies
+  at once can announce a shipment that did not happen (Spree's own fulfil endpoint
+  behaves the same).
+- `ImageUrl` uses the media's still image, so a video thumbnail exports its
+  poster. It is still a root-relative path.
+- The export returns **50 fulfillments per page**, as documented. (pagy 43, which
+  Spree 6 requires, ignores the option the gem used to set this and would have
+  given 25.) A `page` that is not a number is read as page 1.
+- The integration appears in Spree 6's dashboard under the shipping group, with a
+  description, logo and link to the README. Its form is generated from the
+  username and password preferences. Spree 6's migration copies the password into
+  `secret_preferences` as plain text, and `bin/rake spree:upgrade` encrypts it
+  when Active Record encryption keys are configured.
+- Both endpoints now run on a plain `ActionController::Base` controller, since
+  Spree 6 removed the base controller and helper the 5.x one used.
+
+### Added
+
+- **`/shipstation/<integration id>`** (`GET` and `POST`, with or without `.xml`)
+  serves the store of the active ShipStation integration with that `int_` prefixed
+  id. Spree 6 no longer picks the store from the request's host, so a multi-store
+  host points each store's ShipStation at its own integration's URL. The bare
+  `/shipstation` path is unchanged and belongs to the default store.
+- **Ship notices are matched on ShipStation's `OrderID`** when the notice's XML
+  body carries it. A new fulfillment's number is its place in its order, so when
+  Spree deletes a parcel whose items were all moved out, the parcels after it
+  take new numbers; the `OrderID` (the fulfillment's id) does not change. A notice
+  whose `OrderID` belongs to another order is refused with `400` ("Shipment ...
+  does not match order id ..."), and one for a parcel Spree has deleted since
+  ShipStation imported it is refused with `400` instead of fulfilling the sibling
+  that now has its number; re-import the order from ShipStation. A notice without
+  an `OrderID` is matched on its number.
+- **The `carrier` ShipStation sends** is recorded on the delivery when it matches
+  one of Spree's `tracking_carriers` (for example `UPS` or `Royal Mail`). Otherwise
+  Spree detects the carrier from the tracking number.
+- `GET /shipstation` without the `.xml` extension answers with XML.
+- An integration whose stored username or password is blank refuses every request.
+
+### Removed
+
+- The gem's own payment-capture code and its use of **`auto_capture_on_dispatch`**.
+  Spree 6's `capture_method` replaces that setting, and Spree's upgrade task
+  carries it over to the store's `capture_method`.
+- The `Spree::Shipment` decorator and its `exportable` and `between` scopes. The
+  gem no longer patches core models; `Spree::Shipstation::ExportQuery` selects what
+  is exported.
+- The ERB admin form, the asset manifest and the `spree_extension` dependency.
+
+### Internal
+
+- Specs run against the real routes and Spree's real fulfil workflow, with only
+  ShipStation's side simulated. The suite runs with no deprecation warnings.
+- CI tests the oldest and newest Spree 6 the gem allows (6.0.0 and the latest
+  release) on Ruby 3.3 and 4.0, weekly as well as on pushes.
+
 ## 5.0.1
 
 ### Fixed

data/Gemfile

@@ -2,15 +2,19 @@
 
 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"
+# Constrained here because the gemspec no longer declares it; Bundler 2 would
+# otherwise resolve 0.6.3, which is broken on Spree 6.
+gem "spree_dev_tools", "~> 1.0"
 gem "standard"
 gem "sqlite3"
 
+# CI runs a matrix of Spree versions. SPREE_VERSION pins one (e.g. "6.0.0");
+# left unset, Bundler resolves the newest release the gemspec allows.
+spree_version = ENV.fetch("SPREE_VERSION", "")
+gem "spree", spree_version unless spree_version.empty?
+
 gemspec

data/README.md

@@ -3,15 +3,25 @@
 ![CI](https://github.com/aypex-io/spree-shipstation/workflows/CI/badge.svg)
 ![Standard Rb](https://github.com/aypex-io/spree-shipstation/workflows/Standard%20Rb/badge.svg)
 
-The spree-shipstation integration connects your Spree stores with [ShipStation](https://www.shipstation.com), allowing ShipStation to pull shipments from your store, and when a shipment is sent, update the order with a tracking number and mark it as shipped.
+The spree-shipstation integration connects your Spree stores with [ShipStation](https://www.shipstation.com), allowing ShipStation to pull the fulfillments that are ready to ship from your store, and when one is sent, update the order with a tracking number and mark it as fulfilled.
 
+## Requirements
+
+- Spree 6 (`~> 6.0`)
+- Ruby 3.3 or newer
+
+Spree 5 stores stay on the 5.0.x releases, which live on the [`5-0-stable`](https://github.com/aypex-io/spree-shipstation/tree/5-0-stable) branch:
+
+```ruby
+gem "spree-shipstation", "~> 5.0"
+```
 
 ## Installation
 
 1. Add this extension to your Gemfile with this line:
 
     ```ruby
-    gem "spree-shipstation"
+    gem "spree-shipstation", "~> 6.0"
     ```
 
 2. Install the gem using Bundler
@@ -24,7 +34,7 @@ The extension registers itself with Spree's integration framework automatically
 
 ### Step 1: Configuring Spree
 
-Visit the **Integrations** section of your Spree store and configure the ShipStation integration by creating a unique username and password.
+Visit the **Integrations** section of your Spree dashboard and configure the ShipStation integration (listed with the shipping integrations) by creating a unique username and password. The username is 10 to 30 characters of letters, numbers and `. _ @ + -`; the password is 20 to 60 characters and needs an uppercase letter, a number and a special character, one of `! @ # $ % ^ & * ( ) , . ? " : { } | < >`. Other characters such as `-`, `_`, `+` and `=` may appear but do not count as the special character.
 
 ### Step 2: Configuring ShipStation
 
@@ -34,41 +44,117 @@ Enter the following details:
 
 - **Username**: The username you created in Step 1.
 - **Password**: The password you created in Step 1.
-- **URL to custom page**: `https://your-store-domain.com/shipstation.xml`.
+- **URL to custom page**: `https://shop.example.com/shipstation.xml`.
+
+That URL belongs to your **default store**. Any other store (a multi-store setup) must use the URL that names its ShipStation integration:
+
+```
+https://shop.example.com/shipstation/int_abc123.xml
+```
+
+`int_abc123` stands for the integration's prefixed ID, which starts with `int_`. In a Rails console, `Spree::Integrations::Shipstation.all.map(&:prefixed_id)` lists them. The credentials are always the ones set on that integration. The `.xml` is optional on both URLs.
+
+### Order status
 
-There are five shipment states for an order (= shipment) in ShipStation. These states do not
-necessarily align with Spree, but you can configure ShipStation to create a mapping for your
-specific needs. Here's the default mapping:
+Every order the gem sends has the status `ready`, so in ShipStation's Custom Store settings map `ready` to **Awaiting Shipment**. ShipStation's other statuses are never sent: the gem exports only fulfillments that can ship now, and ShipStation marks one as shipped itself once the label exists.
 
-ShipStation description | ShipStation status | Spree status
-------------------------|--------------------|---------------
-Awaiting Payment        | `unpaid`           | `pending`
+ShipStation description | ShipStation status | Sent by the gem
+------------------------|--------------------|----------------
 Awaiting Shipment       | `paid`             | `ready`
-Shipped                 | `shipped`          | `shipped`
-Cancelled               | `cancelled`        | `cancelled`
-On-Hold                 | `on-hold`          | `pending`
+Anything else           | —                  | never; only `ready` is exported
+
+## What ShipStation pulls
+
+Spree 6 splits an order into fulfillments (parcels), and the gem exports one ShipStation order per fulfillment. An order with several fulfillments therefore appears once for each, every copy carrying the order's totals.
+
+A fulfillment is exported when all of these hold:
+
+- it belongs to the store and is still **unfulfilled**;
+- its order is **placed**, so drafts and canceled orders are left out;
+- its order is **paid**: paid, overcharged or partially refunded; or it owes nothing (a total of zero); or, on a store whose capture method is `on_dispatch` or `manual`, it is only authorized, or partially paid with the rest authorized (mixed tender, such as store credit plus a card) (see [Payment capture](#payment-capture));
+- **none of its items is backordered**;
+- it is **not a pickup**: fulfillments collected in person (pickup or pickup point delivery methods) are not shipped.
+
+Apart from the pickup rule, these are most of the checks Spree makes again when the parcel is fulfilled, so ShipStation is rarely offered a parcel Spree would refuse. When it is fulfilled, Spree also checks that the stock location has the units on hand, and the limits under [Payment capture](#payment-capture) apply. A parcel refused then gets a `400` with Spree's reason.
+
+ShipStation's `start_date` and `end_date` (`MM/DD/YYYY HH:MM`, UTC) limit the export to fulfillments whose own or whose order's last update falls in that window. A date the gem cannot read is ignored. Results are ordered by last update, oldest first.
+
+`OrderID` is the fulfillment's id and `OrderNumber` its number. Fulfillments created on Spree 6 are numbered after their order, for example `R1001-F1`; fulfillments created before 6.0 keep the number they already had, so what ShipStation already holds does not change.
+
+## What happens on a ship notice
+
+When a label is created, ShipStation posts to the same URL with `order_number` (the `OrderNumber` it was given), `tracking_number` and `carrier` in the query string, and the notice again as an XML body that carries the `OrderID` it was given. The gem finds that fulfillment in the store, by its `OrderID` when the body carries one and by its number otherwise, and:
+
+- **fulfils it** through Spree's own fulfil workflow, recording the tracking number, and answers `200`;
+- records the carrier when ShipStation's carrier name matches one of Spree's `tracking_carriers` (for example `UPS`, `USPS`, `FedEx` or `Royal Mail`); otherwise Spree detects it from the tracking number;
+- if the fulfillment is **already fulfilled or delivered**, only records or corrects the tracking number and answers `200`. ShipStation retries, and a retry does not fulfil the parcel or publish the event again. The one exception is a tracking number that is already on a different delivery of the same fulfillment, which is refused (below);
+- otherwise answers `400` with a plain-text reason and changes nothing. ShipStation shows the reason to the warehouse. The reasons include:
+  - `Could not find shipment with number …`, for an unknown or blank number, or an `OrderID` whose fulfillment no longer exists;
+  - `Shipment … does not match order id …`, when the `OrderID` belongs to a fulfillment of another order;
+  - `Tracking number is required`;
+  - `Shipment … is canceled`;
+  - Spree's own message when it refuses to fulfil, for example `This order is not paid for yet`, or its message about backordered units;
+  - `Could not capture payment: …`, when the gateway declines a capture on dispatch;
+  - `Tracking number has already been taken`, when a retry for a fulfilled parcel names a tracking number that already belongs to another delivery of the same fulfillment.
+
+The gem never forces a fulfilment past Spree's paid and backordered checks, and never splits a fulfillment.
+
+### Why the `OrderID` comes first
+
+A new fulfillment's number is its place in its order: `R1001-F2` is the second parcel. When every item is moved out of a parcel (with the dashboard's split or change-location actions, say), Spree deletes it, and the parcels after it move up a place and take new numbers. A fulfillment's id never changes, so the gem trusts the `OrderID` over the number. A notice for a renumbered parcel still fulfils the right one, and a notice for a parcel Spree deleted after ShipStation imported it is refused with a `400` rather than fulfilling a sibling that now has its number. Re-import the order from ShipStation to pick up its parcels as they now are.
+
+So, in an order with several parcels, avoid moving every item out of a parcel ShipStation has already imported: that parcel is no longer valid in ShipStation.
 
 ## Configuration
 
-### Payment capture on dispatch
+### Payment capture
+
+The gem has no capture setting of its own. Capture on dispatch follows Spree 6's `capture_method`, set on the store and optionally overridden by each payment method:
+
+- `checkout` (the default) charges as the order is placed. Authorized orders are not yet paid, so they are not exported.
+- `on_dispatch` authorizes at checkout and charges when the fulfillment is fulfilled. The gem exports authorized orders, and partially paid ones whose rest is authorized, and Spree captures the payment as the ship notice is applied. If the gateway declines, ShipStation gets a `400` ("Could not capture payment: …") and nothing is kept: the fulfillment stays unfulfilled, the payment stays pending and any tracking number written during the attempt is rolled back. The next retry, or the merchant's fix to the payment, fulfils it.
+- `manual` authorizes at checkout and leaves charging to your staff. The gem exports authorized and partially paid orders, and Spree lets them ship without charging them.
+
+Two limits:
+
+- Whether an authorized or partially paid order is exported depends on the **store's** capture method only. A store that captures at checkout but has a payment method that overrides it to `on_dispatch` never exports that method's authorized orders, and does so silently. To export them, set the store's capture method to `on_dispatch` or `manual`, bearing in mind that this changes it for every payment method that has no setting of its own. In the reverse case, a store set to `on_dispatch` with a payment method overridden to capture at checkout, an authorized order is exported and the ship notice is then refused with Spree's reason.
+- A partially refunded order is exported, because the rest of it may still ship, but Spree compares the net captured amount (after refunds) with what the order was due, so the ship notice may still be refused with Spree's reason. Likewise a partially paid order ships only while the rest is authorized on payment methods that defer capture.
+
+### Fulfillment providers
+
+Give the delivery methods whose parcels ShipStation ships Spree's **Manual** fulfillment provider. On a ship notice, Spree's fulfil workflow also buys a label and tells the delivery method's provider that the parcel has shipped; for Manual, both do nothing. A provider that buys labels or hands parcels to a 3PL would act a second time for a parcel ShipStation has already shipped. A declined capture on dispatch does not undo those calls either, even though everything Spree wrote is rolled back.
 
-The integration respects Spree's `auto_capture_on_dispatch` setting. When enabled in your Spree store, pending payments are captured automatically before a shipment is marked as shipped. If a payment capture fails, an error is returned to ShipStation (HTTP 400), preventing the shipment from being marked as shipped until the issue is resolved.
+### Telling the customer
 
-Payment capture happens **synchronously** within the shipnotify webhook request (inside a database transaction) so that a shipment is never marked as shipped against an uncaptured payment. ShipStation automatically retries failed webhook deliveries, and the operation is designed to be safe to repeat: a shipment that is already `shipped` is not shipped again, and only still-pending payments are captured. If your payment gateway is slow, be aware that the capture round-trip occurs in the request cycle.
+Spree core does not send a shipped email by itself (as of Spree 6.0.1). When a fulfillment is fulfilled, Spree publishes the `fulfillment.fulfilled` event, and the gem asks for the customer to be notified (`notify_customer: true`). Your application decides whether, and how, to tell the customer, by subscribing to `fulfillment.fulfilled`. Without a subscriber, no shipped email goes out.
+
+One caveat: when a capture on dispatch is declined, Spree publishes `fulfillment.fulfilled` synchronously inside the transaction that is then rolled back. A subscriber that notifies at once, rather than after the transaction commits, can tell a customer their order has shipped when the attempt was declined and nothing was kept. Spree's own fulfil endpoint behaves the same way, so if that matters to you, make your subscriber send only after the transaction has committed.
 
 ### Pagination
 
-The export endpoint returns up to **50 shipments per page**. ShipStation handles pagination automatically using the `page` query parameter.
+The export endpoint returns up to **50 fulfillments per page**. ShipStation handles pagination automatically using the `page` query parameter; a `page` that is not a number is read as the first page.
+
+## Upgrading from 5.0
+
+- Bump the gem to `~> 6.0` alongside your upgrade to Spree 6.
+- The gem has no data migration of its own. Spree 6's migrations rename shipments to fulfillments, keeping their ids and numbers, and copy the integration's password into `secret_preferences` as plain text. `bin/rake spree:upgrade` (next step) encrypts it when Active Record encryption keys are configured.
+- **Run `bin/rake spree:upgrade` right after `db:migrate`, before ShipStation next polls.** Spree's upgrade tasks move 5.x shipment statuses to fulfillment statuses (`ready` and `pending` become `unfulfilled`, `shipped` becomes `fulfilled`), backfill the delivery-method providers the pickup rule reads, recompute the payment and fulfillment statuses of orders whose shipments were pending, ready or shipped, encrypt stored secrets, and carry settings such as `auto_capture_on_dispatch` over to the store's `capture_method`. An order in another state, such as partly shipped or backordered, keeps its 5.x payment status until Spree next updates it. Until then the export is empty, since no fulfillment is `unfulfilled` yet. Meanwhile a parcel still marked `shipped` is treated as fulfilled: a ship notice only records its tracking.
+- **ShipStation needs no changes** for the default store: same URL, same credentials, same `OrderNumber` for parcels it has already imported, same `ready` status.
+- New fulfillments are numbered like `R1001-F1`. A store other than the default must use `/shipstation/<integration id>` (see Step 2): 5.x picked the store from the request's host, and Spree 6 does not, so the bare URL serves only the default store.
+- Capture on dispatch now follows Spree 6's `capture_method` setting (on the store or the payment method). Spree's upgrade task carries `auto_capture_on_dispatch` over to the store's `capture_method`.
+- As before, unpaid or backordered fulfillments do not appear in ShipStation until they can ship: 5.x exported only `ready` shipments.
+- A ship notice for something Spree will not ship is answered with `400` and Spree's reason.
+- Spree 6 core sends no shipped email on its own, so subscribe to `fulfillment.fulfilled` if your store relied on the 5.x email (see [Telling the customer](#telling-the-customer)).
 
 ## Security considerations
 
-- **Serve the endpoints over HTTPS.** Both `/shipstation` endpoints authenticate with HTTP Basic Auth, which transmits the configured username and password (base64-encoded) on every request. Always terminate these requests over TLS in production so the credentials are not exposed in transit. Credentials are compared in constant time to avoid timing attacks.
-- **Consider rate limiting.** The gem does not throttle authentication attempts. If you want brute-force protection, add it at the application or edge layer (for example, [`rack-attack`](https://github.com/rack/rack-attack)). The enforced credential length (10–30 character username, 20–60 character complex password) already makes guessing impractical.
-- **Response codes.** When no active ShipStation integration is configured, the endpoints respond with `404` before authentication is checked; a configured-but-unauthenticated request responds with `401`. This is intentional, but be aware it reveals whether the integration is configured.
+- **Serve the endpoints over HTTPS.** Both `/shipstation` endpoints authenticate with HTTP Basic Auth, which transmits the configured username and password (base64-encoded) on every request. Always terminate these requests over TLS in production so the credentials are not exposed in transit. Credentials are compared in constant time to avoid timing attacks, and an integration whose stored username or password is blank refuses every request.
+- **Consider rate limiting.** The gem does not throttle authentication attempts. If you want brute-force protection, add it at the application or edge layer (for example, [`rack-attack`](https://github.com/rack/rack-attack) or Rails' `rate_limit`). The enforced credential length (10–30 character username, 20–60 character complex password) already makes guessing impractical.
+- **Response codes.** When no active ShipStation integration is configured, the endpoints respond with `404` before authentication is checked; a configured-but-unauthenticated request responds with `401`. This is intentional, but be aware it reveals whether the integration is configured. An integration that is switched off is the same as none.
 
 ## Performance
 
-The export query eager-loads its association graph to avoid N+1 queries. The `exportable` scope filters shipments by `state` and orders them by `updated_at`, joining and filtering orders by their `updated_at`. The gem ships no migrations of its own; on large stores, ensure the relevant Spree core columns (`spree_shipments.state`, `spree_shipments.updated_at`, `spree_orders.updated_at`) are adequately indexed in your application's database.
+The export query eager-loads its association graph to avoid N+1 queries. It selects unfulfilled fulfillments, joins their orders and filters by payment status, and orders and windows by `updated_at`. The gem ships no migrations of its own. Spree 6's schema indexes `spree_fulfillments.status` and `spree_orders.payment_status`, but not `spree_fulfillments.updated_at` or `spree_orders.updated_at`; on large stores, consider indexing those two in your application's database.
 
 ## Usage
 
@@ -76,9 +162,10 @@ There's nothing you need to do. Once properly configured, the integration just w
 
 ### Compatibility
 
-This extension works with the following Spree versions:
-- 5.x
-
+spree-shipstation | Spree | Ruby
+------------------|-------|------
+6.0.x             | 6.x (`~> 6.0`) | 3.3 or newer
+5.0.x, on [`5-0-stable`](https://github.com/aypex-io/spree-shipstation/tree/5-0-stable) | 5.x | 3.1 or newer
 
 ### Testing
 
@@ -94,6 +181,13 @@ To run the tests use:
 bundle exec rake
 ```
 
+CI runs the suite against Spree 6.0.0 and the newest 6.x release. To test against a specific Spree version locally:
+
+```shell
+SPREE_VERSION=6.0.0 bundle update spree
+bundle exec rake
+```
+
 ### Code Formatting
 
 To check your code formatting with [Standard Rb](https://github.com/testdouble/standard) run:
@@ -110,10 +204,7 @@ bundle exec standardrb --fix
 
 ## Releasing
 
-```bash
-bundle exec gem bump -p -t
-bundle exec gem release
-```
+Bump `Spree::Shipstation::VERSION` in `lib/spree/shipstation/version.rb`, add the release to the changelog, and merge. Pushing a `v*` tag publishes the gem to RubyGems through the Release workflow.
 
 ## License
 

data/Rakefile

@@ -23,19 +23,18 @@ task :test_app do
   # literal `require ENV['LIB_NAME']` and templates the same string into the
   # generated spec/dummy/config/application.rb.
   ENV["LIB_NAME"] = "spree/shipstation"
-  Rake::Task["extension:test_app"].execute(
-    install_admin: true
-  )
+  # Spree 6's extension:test_app takes no install_admin option.
+  Rake::Task["extension:test_app"].execute
 end
 
 namespace :dummy do
   # Spree's test_app task runs `db:migrate` in the generator's own process with
-  # output redirected to /dev/null and its exit status ignored. On the heavier
-  # Spree 5.3+/5.4 setup path (admin install + Tailwind/asset build) that step
-  # can be interrupted mid schema-dump, leaving a TRUNCATED db/schema.rb. Rails
-  # then loads that broken dump on the next migrate and fails, so the dummy
-  # database ends up empty and the whole suite errors with
-  # "Could not find table 'spree_*'".
+  # output redirected to /dev/null and its exit status ignored. If a migration
+  # fails partway (for example, Spree's preferences conversion eager loads the
+  # whole app, so any class that fails to load stops it), the dummy database is
+  # left half-built and the whole suite errors with weird failures or
+  # "Could not find table 'spree_*'", with no hint of the cause. Rails then
+  # loads a possibly truncated db/schema.rb dump on the next migrate too.
   #
   # Make setup deterministic: discard any (possibly corrupt) schema dump and
   # rebuild the database from the migration files, in a fresh process and

data/app/controllers/spree/shipstation_controller.rb

@@ -2,30 +2,51 @@
 
 module Spree
   ##
-  # HTTP endpoints ShipStation polls for ready shipments and posts ship notices to.
+  # HTTP endpoints ShipStation polls for ready parcels and posts ship notices to.
   #
-  class ShipstationController < Spree::BaseController
-    include Spree::IntegrationsHelper
+  # 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
+
+    # 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 :ensure_active_integration
+    before_action :find_integration
     before_action :authenticate_shipstation
 
     ##
-    # XML export of ready shipments for ShipStation to pull.
+    # 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 }
@@ -33,12 +54,15 @@ module Spree
     end
 
     ##
-    # Applies a ship notification from ShipStation and marks the shipment shipped.
+    # 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}")
@@ -47,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?
 
@@ -61,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

@@ -39,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
@@ -47,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