@spree/docs 0.1.144 → 0.1.146

package/dist/developer/how-to/custom-order-routing.md

@@ -233,9 +233,6 @@ First register the class so it's selectable (this is the allowlist the model val
 ```ruby
 # config/initializers/spree.rb
 Spree.order_routing.strategies << 'Acme::Oms::Strategy'.constantize
-
-# Optionally drop the legacy escape hatch:
-# Spree.order_routing.strategies.delete(Spree::OrderRouting::Strategy::Legacy)
 ```
 
 Then select it by class name string — set on `Spree::Store` (default) or `Spree::Channel` (override). Setting an unregistered class fails validation.

package/dist/developer/upgrades/5.4-to-5.5.md

@@ -241,7 +241,7 @@ store.update!(preferred_order_routing_strategy: 'Spree::OrderRouting::Strategy::
 
 The Legacy strategy delegates to `Spree::Stock::Coordinator`, which is the exact pre-5.5 packing pipeline — every active stock location is packed, the Prioritizer distributes inventory units across the resulting packages, and no merchant routing rules are consulted. Your existing customizations on `Coordinator`, `Packer`, `Prioritizer`, and the splitters keep working unchanged.
 
-> **WARNING:** `Spree::OrderRouting::Strategy::Legacy` and `Spree::Stock::Coordinator` are slated for removal in Spree 6.0. Use this only as a temporary escape hatch while you evaluate the new Rules strategy. New 5.5+ installations should stay on the default Rules strategy.
+> **WARNING:** `Spree::OrderRouting::Strategy::Legacy` **was removed in Spree 6.0**. It exists only on the 5.5/5.6 line, as a temporary escape hatch while you evaluate the Rules strategy. Stores still carrying this value fall back to the default Rules strategy on 6.0 (with a logged warning), so clear the preference before upgrading.
 
 ## Behavior changes to review
 

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -182,6 +182,74 @@ The full address surface is shared by Cart and Order through `Spree::Purchase::A
 - A signed-in customer entering checkout gets blank address slots **auto-filled from their saved defaults**.
 - **`use_billing` is deprecated** (removed in 6.1): the shipping address is canonical — use `use_shipping` to copy ship → bill.
 
+## Returns, exchanges and claims
+
+The `ReturnAuthorization → CustomerReturn → Reimbursement` chain is replaced by three first-class records that each belong directly to an order: **`Spree::Return`** (items come back, money goes back), **`Spree::Exchange`** (items come back, different items go out), and **`Spree::Claim`** (something went wrong in delivery — no items required back).
+
+The old classes are **gone with no bridge**, so calls raise `NameError`:
+
+| Removed | Use instead |
+|---|---|
+| `Spree::ReturnAuthorization` | `Spree::Return` or `Spree::Exchange` |
+| `Spree::CustomerReturn` | `Spree::Return` — receiving is a status on the same record |
+| `Spree::Reimbursement`, `Spree::ReimbursementType` | `Spree::Returns::Refund` (a workflow, not a model) |
+| `Spree::ReturnItem` | `Spree::ReturnLineItem` / `Spree::ExchangeLineItem` / `Spree::ClaimLineItem` |
+| `Spree::ReturnItem::EligibilityValidator::*` | the `validate` hook — see below |
+| `Spree::ReturnAuthorizationReason` | `Spree::ReturnReason` (constant alias kept until 6.1, with a warning) |
+
+> **NOTE:** **The legacy tables are not dropped.** They stay through 6.1 as the data migration's source and rollback path. Run `spree:upgrade:migrate_returns` to copy the history onto the new models — it's resumable, and it aborts if any row fails so an upgrade can't silently proceed on partial history.
+
+### No state machines
+
+New records carry a plain `status` string with an inclusion validation. Every transition is a workflow — `Spree::Returns::Approve`, `Returns::Receive`, `Returns::Refund`, `Exchanges::Fulfill`, `Claims::Resolve`, and so on. **Nothing happens in a model callback or transition callback**, so code that hooked `before_transition` on the old machines has no equivalent; move it to a workflow hook or an event subscriber.
+
+Statuses are extensible but additive only, through `Spree::HasStatus`:
+
+```ruby
+Spree::Return.add_status('inspecting', after: 'received')
+```
+
+### Eligibility is a hook, not a validator chain
+
+`ReturnItem::EligibilityValidator::Default` chained five validators. Only one was policy; the rest were invariants, so they moved to different places:
+
+| Old validator | Where the rule lives now |
+|---|---|
+| `TimeSincePurchase` | `Spree::Returns::EligibilityValidator`, registered on the `validate` hook |
+| `OrderCompleted` | inline guard in `Returns::Create` |
+| `InventoryShipped` | structural — only fulfillment items can be returned, and quantities are checked against what shipped |
+| `NoReimbursements` | quantity math — prior return line items are subtracted, so units can't come back twice |
+| `RMARequired` | gone: the `Return` **is** the request, so there is nothing to require |
+
+Core ships exactly one policy rule — a return window read from `market.preferred_return_window_days` (default 30), per market because return windows are a regional legal matter. **Staff can override it**: when `created_by` is present the window is advisory, so a supervisor can accept a late return without a code change.
+
+> **WARNING:** Four returns settings are **deprecated and read by nothing** — they still exist so applications don't crash at boot, but they have no effect and now emit a deprecation warning when read or written:
+> 
+>   | Deprecated setting | Use instead |
+>   |---|---|
+>   | `return_eligibility_number_of_days` | `preferred_return_window_days` on `Spree::Market`, or a `returns.create.validate` hook |
+>   | `restock_inventory` | `Spree::ReturnLineItem#resellable`, decided per line item at receiving |
+>   | `expedited_exchanges`, `expedited_exchanges_days_window` | `Spree::Exchange` and the `Exchanges::Fulfill` workflow |
+
+Replace it by swapping the handler:
+
+```ruby
+Spree.hooks.unregister('returns.create.validate', 'Spree::Returns::EligibilityValidator')
+Spree.hooks.register('returns.create.validate', 'MyStore::ReturnPolicy')
+```
+
+A handler receives the workflow (so it can read `order`, `items`, `created_by`, `order.market`) and calls `workflow.reject!(message)` to veto. Every one of the fifteen transitions has a leading `validate` hook, so the same seam gates approving, receiving and refunding.
+
+> **WARNING:** `requires_manual_intervention?` has no equivalent. The old validators could mark an item eligible-but-flagged for manual review; a handler now either accepts or vetoes. If you relied on that middle state, model it explicitly — an added status, or a metafield your handler sets.
+
+### Other behavioral changes
+
+- **`Return#refunded_total` counts store credits.** Store credit is a separate ledger and never creates a `Spree::Refund` row, so the old sum reported zero for a store-credit refund.
+- **`Order#outstanding_balance` dropped its reimbursement term** rather than replacing it — refunds already net out of `payment_total`, so that term was double-counting.
+- **The reimbursement email is now `Spree::ReturnMailer#refunded_email`**, sent on `return.refunded` (in the optional `spree_emails` gem, like the other transactional mail).
+- **`Refund#originator`** points at the new records.
+- Events are `return.requested` / `.approved` / `.received` / `.refunded` / `.canceled`, and the matching `exchange.*` and `claim.*` families.
+
 ## Dependency injection changes
 
 6.0 introduces `*_workflow` keys for the flows that graduated to the workflow tier. The old `*_service` keys **stay settable and readable one release so applications don't crash at boot — but a legacy write is stashed, not applied**: a class written against the old service contract is not interchangeable with the workflow the new call sites consume. Reads return your stashed class (legacy code calling its own override keeps working), falling back to the workflow. Removed in 6.1.
@@ -209,6 +277,73 @@ Removed keys (their classes no longer exist): `carts_validate_service` (completi
 
 If you override a workflow seam, subclass the shipped workflow (or implement the same `perform` keyword contract) — workflow arguments are plain Ruby keywords, so a mismatch raises `ArgumentError` at call time, not silently.
 
+## Removed in 6.0
+
+These were deprecated in 5.x and are **gone now** — there is no bridge, so calls raise `NoMethodError`. Most were one-line delegations to a replacement that already exists.
+
+| Removed | Use instead |
+|---|---|
+| `Product#default_image`, `#featured_image`, `#primary_image` | `#primary_media` |
+| `Variant#default_image`, `#primary_image` | `#primary_media` |
+| `Address#user_default_billing?`, `#user_default_shipping?` | `#is_default_billing?`, `#is_default_shipping?` |
+| `OptionType#color?` | `#color_swatch?` |
+| `Category#set_store` | `#ensure_store` |
+| `Category.for_taxonomy` | `.for_store` |
+| `Store#admin_users` | `#users` |
+| `Store#supported_shipping_zones` | `#countries_with_shipping_coverage` |
+| `Spree.searcher_class` | `Spree.search_provider` |
+| `Spree.admin_user_class.spree_admin_created?` | `.spree_admin.exists?` |
+| `BaseMailer#set_email_locale` | wrap the action body in `with_store_locale(store) { ... }` |
+| `Asset#styles`, `ImageMethods#generate_url`, `#original_url` | Active Storage variants with `cdn_image_url` |
+| `Spree::ImageMethods`, `Spree::NumberAsParam` (concerns) | deleted — `NumberAsParam` was already a no-op; prefixed IDs come from `Spree::PrefixedId` |
+| `Product.with_option`, `.with`, `.in_name`, `.in_name_or_keywords`, `.in_name_or_description`, `.with_ids`, `.for_user` | `.with_option_value`, `.search`, `where(id: ids)` |
+| `Product.add_search_scope` | plain `scope :name, -> { ... }` |
+| `Spree::Image::Configuration::ActiveStorage` | deleted — an empty no-op module; all logic lives in `Spree::Asset` |
+| `Spree::OrderRouting::Strategy::Legacy` | `Spree::OrderRouting::Strategy::Rules` (see below) |
+
+### The Legacy order-routing strategy is gone
+
+`Spree::OrderRouting::Strategy::Legacy` — the pre-5.5 escape hatch that delegated straight to `Spree::Stock::Coordinator` and consulted no routing rules — is removed and no longer registered in `Spree.order_routing.strategies`.
+
+A store or channel still carrying `preferred_order_routing_strategy: 'Spree::OrderRouting::Strategy::Legacy'` **keeps working**: `Order#order_routing_strategy` ignores unregistered classes, logs a warning, and falls back to `Strategy::Rules`. Clear the stale preference to silence the warning — note that saving such a record now fails validation, since the value is no longer in the registry.
+
+`Spree::Stock::Coordinator` itself stays — cart fulfillment building, exchanges, and claims still use it.
+
+### `Store.default` no longer builds a store
+
+`Spree::Store.default` returned an **unpersisted** `Store.new(default: true)` when no default store existed. It now returns `nil`.
+
+This matters more than it looks: `Spree::Current.store` falls back to `Store.default`, and every `Spree::SingleStoreResource` model resolves its own `store` from `Spree::Current.store`. Without a default store, those records now fail validation with "Store can't be blank" instead of silently attaching to a throwaway store.
+
+Make sure a default store exists before creating store-scoped records, and set `Spree::Current.store` in jobs, rake tasks, and tests that run outside a request.
+
+### The `DefaultPrice` concern is gone — `price_in` / `set_price` is the interface
+
+`Spree::DefaultPrice` and the `enable_legacy_default_price` setting are removed, along with the `has_one :default_price` association on `Variant`. Prices live in `spree_prices`, one row per currency, and a price is always an **amount plus a currency** — there is no longer an implicit "the" price.
+
+The single-currency accessors are gone from both `Variant` and `Product`:
+
+| Removed | Use instead |
+|---|---|
+| `variant.price`, `product.price` | `variant.price_in(currency).amount` or `amount_in(currency)` |
+| `variant.price = x`, `product.price = x` | `variant.set_price(currency, x)` |
+| `variant.default_price` | `variant.price_in(currency)` |
+| `variant.currency`, `product.currency` | the currency is an argument now — pass the one you mean |
+| `display_price`, `display_amount` | `price_in(currency).display_amount` |
+| `compare_at_price=` | `set_price(currency, amount, compare_at_amount)` |
+| `display_compare_at_price` | `price_in(currency).display_compare_at_amount` |
+| `price_including_vat_for(opts)` | `price_in(currency).price_including_vat_for(opts)` |
+| `has_default_price?` | `prices.base_prices.exists?(currency: currency)` |
+
+The `compare_at_price` **reader** (which resolves against `cost_currency`) is unchanged on both `Variant` and `Product` — only the writer is gone. So are the `price_in` / `amount_in` / `compare_at_amount_in` readers.
+
+Also note:
+
+- **Ransack:** `default_price` is no longer a searchable association on `Variant`; query `prices` instead.
+- **`Spree::PermittedAttributes`:** the dead `:price` and `:compare_at_price` entries are dropped from `product_attributes` and `variant_attributes`. Prices were already written as nested `prices: [{ amount:, currency: }]` under variants — the top-level keys had no writer behind them.
+- Localized number parsing still happens: `Spree::Price#amount=` runs `Spree::LocalizedNumber.parse`, so `set_price(currency, '1,599.99')` works as `price=` did.
+- The variant validation that inferred a missing price from the product's default variant is gone. Set prices explicitly (the product and variant factories already do).
+
 ## Deprecated in 6.0, removed in 6.1
 
 Every rename keeps the legacy name working for one release with a deprecation warning. The notable ones:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.144",
+  "version": "0.1.146",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",