Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add fulfillment providers with digital auto-fulfillment and lifecycle events (core rewrite Wave 4)
Damian Legawiec586999eb048e
diff --git a/docs/plans/6.0-core-rewrite-tasks.md b/docs/plans/6.0-core-rewrite-tasks.mdindex 299f898f08..a1655461cc 100644--- a/docs/plans/6.0-core-rewrite-tasks.md+++ b/docs/plans/6.0-core-rewrite-tasks.md@@ -188,9 +188,17 @@ Runs after Wave 2 (tables born with `fulfillment_id`). Can proceed in parallel w## Wave 4 — Fulfillment providers + lifecycle events (`6.0-fulfillment-and-delivery.md` P4) — parallelizable with Wave 3-- [ ] **T4.1 Provider strategy:** `FulfillmentProvider::{Base,Manual,Digital,Pickup,PickupPoint}`; string class name on DeliveryMethod, constantized at call time; `Spree.fulfillment_providers` + `Spree.fulfillment_types` registries (open strings, no inclusion validation); wired into fulfillment transitions.-- [ ] **T4.2 Digital auto-fulfillment (new behavior):** `FulfillmentProvider::Digital` fires `fulfill!` on order completion and creates DigitalLinks **idempotently, per quantity** — the non-idempotent checkout-callback link creation is removed here (wired from today's `finalize!`; re-pointed to pipeline step F5 in Wave 5).-- [ ] **T4.3 Events:** `fulfillment.{ready,fulfilled,canceled,resumed}` + `publishes_lifecycle_events`; `order.fulfilled` when the last fulfillment fulfills + `Order#fully_fulfilled?`; one-release dual-emit of legacy `shipment.*` webhooks (Decision 6 — dropped 6.1); `PickupPointProvider::Base` + `PickupPointOption` struct (`find_nearby`/`find_by_external_id`; ephemeral, frozen into `fulfillment.pickup_point_data` on selection).+- [x] **T4.1 Provider strategy:** `FulfillmentProvider::{Base,Manual,Digital,Pickup,PickupPoint}`; string class name on DeliveryMethod, constantized at call time; `Spree.fulfillment_providers` + `Spree.fulfillment_types` registries (open strings, no inclusion validation); wired into fulfillment transitions.+- [x] **T4.2 Digital auto-fulfillment (new behavior):** `FulfillmentProvider::Digital` fires `fulfill!` on order completion and creates DigitalLinks **idempotently, per quantity** — the non-idempotent checkout-callback link creation is removed here (wired from today's `finalize!`; re-pointed to pipeline step F5 in Wave 5).+- [x] **T4.3 Events:** `fulfillment.{ready,fulfilled,canceled,resumed}` + `publishes_lifecycle_events`; `order.fulfilled` when the last fulfillment fulfills + `Order#fully_fulfilled?`; one-release dual-emit of legacy `shipment.*` webhooks (Decision 6 — dropped 6.1); `PickupPointProvider::Base` + `PickupPointOption` struct (`find_nearby`/`find_by_external_id`; ephemeral, frozen into `fulfillment.pickup_point_data` on selection).++### Wave 4 outcome notes (2026-07-29)++- Provider wiring: `Fulfillment#provider` resolves through the selected delivery method with a Manual fallback; `fulfill` transition gated by `provider.can_fulfill?`; `after_fulfill` runs `provider.create_fulfillment` (returned tracking persisted unless an admin already entered one); `after_cancel` runs `provider.cancel_fulfillment`.+- Digital: `ensure_links_for` is the public idempotent per-quantity primitive. `Order#auto_fulfill_provider_fulfillments` (called from finalize!) fulfills auto-fulfill providers through the machine, then tops up links for digital-ASSET line items shipping through other providers (vinyl+download combos keep their completion-time links). `Order#create_digital_links` is a deprecated delegate; the checkout callback is gone.+- Digital delivery method factory + Seeds::DigitalDelivery now set `fulfillment_provider: 'Spree::FulfillmentProvider::Digital'` (the Wave 7 backfill maps DigitalDelivery-calculator methods the same way).+- Events: `fulfillment.{ready,fulfilled,canceled,resumed}` + `order.fulfilled`; legacy `shipment.*` + `order.shipped` dual-emitted in the same publishers (removed 6.1); old `publish_shipment_*` methods are warn-delegates. `Order#fully_fulfilled?` real, `fully_shipped?` deprecated.+- Registries: `Spree.fulfillment_providers` (4 built-ins) + `Spree.fulfillment_types` (5 open strings) as Environment members.---diff --git a/spree/core/app/models/spree/fulfillment.rb b/spree/core/app/models/spree/fulfillment.rbindex 363060c7a3..b3282c262b 100644--- a/spree/core/app/models/spree/fulfillment.rb+++ b/spree/core/app/models/spree/fulfillment.rb@@ -100,14 +100,15 @@ module Spreeendevent :fulfill do- transition from: %i(ready ready_for_pickup canceled), to: :fulfilled+ transition from: %i(ready ready_for_pickup canceled), to: :fulfilled, if: ->(fulfillment) { fulfillment.provider.can_fulfill?(fulfillment) }end- after_transition to: :fulfilled, do: [:after_fulfill, :send_shipment_shipped_webhook, :publish_shipment_shipped_event]+ after_transition to: :ready, do: :publish_fulfillment_ready_event+ after_transition to: :fulfilled, do: [:after_fulfill, :send_fulfillment_fulfilled_webhook, :publish_fulfillment_fulfilled_event]event :cancel dotransition to: :canceled, from: %i(pending ready ready_for_pickup)end- after_transition to: :canceled, do: [:after_cancel, :publish_shipment_canceled_event]+ after_transition to: :canceled, do: [:after_cancel, :publish_fulfillment_canceled_event]event :resume dotransition from: :canceled, to: :ready, if: lambda { |fulfillment|@@ -115,7 +116,7 @@ module Spree}transition from: :canceled, to: :pendingend- after_transition from: :canceled, to: %i(pending ready fulfilled), do: [:after_resume, :publish_shipment_resumed_event]+ after_transition from: :canceled, to: %i(pending ready fulfilled), do: [:after_resume, :publish_fulfillment_resumed_event]after_transition do |fulfillment, transition|fulfillment.state_changes.create!(@@ -212,6 +213,7 @@ module Spreedef after_cancelmanifest.each { |item| manifest_restock(item) }+ provider.cancel_fulfillment(self)enddef after_resume@@ -490,6 +492,23 @@ module Spreeselected_delivery_rate&.delivery_method || delivery_rates.first&.delivery_methodend+ # The fulfillment provider strategy handling this fulfillment's+ # create/track/cancel mechanics — from the selected delivery method,+ # falling back to Manual when no method is selected.+ #+ # @return [Spree::FulfillmentProvider::Base]+ def provider+ delivery_method&.provider || Spree::FulfillmentProvider::Manual.new+ end++ # Commission base for multi-vendor include_shipping: the cost net of+ # fulfillment-attached discounts.+ #+ # @return [BigDecimal]+ def delivery_amount+ cost + discounts.sum(:amount)+ end+# Returns the tax category of the selected shipping rate## @return [Spree::TaxCategory]@@ -584,9 +603,20 @@ module Spreefulfillment_items.each(&:ship!)process_order_payments if Spree::Config[:auto_capture_on_dispatch]touch :fulfilled_at+ run_provider_create_fulfillmentupdate_order_fulfillment_statusend+ # Lets the provider perform its dispatch mechanics; tracking data it+ # returns is persisted unless an admin already entered one.+ def run_provider_create_fulfillment+ result = provider.create_fulfillment(self)+ return unless result.is_a?(Hash)++ new_tracking = result[:tracking_number].presence+ update_column(:tracking, new_tracking) if new_tracking && tracking.blank?+ end+def update_order_fulfillment_statusnew_status = OrderUpdater.new(order).update_fulfillment_statusorder.update_columns(fulfillment_status: new_status, updated_at: Time.current)diff --git a/spree/core/app/models/spree/fulfillment/custom_events.rb b/spree/core/app/models/spree/fulfillment/custom_events.rbindex 1ca760aff5..9d809bddae 100644--- a/spree/core/app/models/spree/fulfillment/custom_events.rb+++ b/spree/core/app/models/spree/fulfillment/custom_events.rb@@ -2,44 +2,80 @@module Spreeclass Fulfillment < Spree.base_class- # Publishes custom shipment events beyond basic lifecycle events.+ # Publishes fulfillment lifecycle events beyond the basic Publishable set.## Events:- # - shipment.shipped: Shipment was shipped- # - order.shipped: All order shipments are shipped- # - shipment.canceled: Shipment was canceled- # - shipment.resumed: Shipment was resumed from canceled state+ # - fulfillment.ready: Fulfillment became ready+ # - fulfillment.fulfilled: Fulfillment was fulfilled+ # - order.fulfilled: All order fulfillments are fulfilled+ # - fulfillment.canceled: Fulfillment was canceled+ # - fulfillment.resumed: Fulfillment was resumed from canceled#- # NOTE: These methods are called from the state machine's after_transition callbacks- # defined in the Shipment model, not via ActiveRecord callbacks.+ # The legacy shipment.* / order.shipped events are dual-emitted for one+ # release (webhook contract bridge — removed in 6.1).#+ # NOTE: These methods are called from the state machine's after_transition+ # callbacks defined in the Fulfillment model, not via ActiveRecord callbacks.module CustomEventsextend ActiveSupport::Concern- def publish_shipment_shipped_event+ def publish_fulfillment_ready_event+ return unless Spree::Events.enabled?++ publish_event('fulfillment.ready')+ end++ def publish_fulfillment_fulfilled_eventreturn unless Spree::Events.enabled?+ publish_event('fulfillment.fulfilled')+ # Legacy name — removed in 6.1publish_event('shipment.shipped')- # Force reload of shipments association to see the new state- order.shipments.reset- publish_order_shipped_event if order.fully_shipped?++ # Force reload of fulfillments association to see the new status+ order.fulfillments.reset+ publish_order_fulfilled_event if order.fully_fulfilled?end- def publish_shipment_canceled_event+ def publish_fulfillment_canceled_eventreturn unless Spree::Events.enabled?+ publish_event('fulfillment.canceled')+ # Legacy name — removed in 6.1publish_event('shipment.canceled')end- def publish_shipment_resumed_event+ def publish_fulfillment_resumed_eventreturn unless Spree::Events.enabled?+ publish_event('fulfillment.resumed')+ # Legacy name — removed in 6.1publish_event('shipment.resumed')end+ # @deprecated Use {#publish_fulfillment_fulfilled_event}; removed in 6.1.+ def publish_shipment_shipped_event+ Spree::Deprecation.warn('Spree::Fulfillment#publish_shipment_shipped_event is deprecated and will be removed in Spree 6.1. Use #publish_fulfillment_fulfilled_event instead.')+ publish_fulfillment_fulfilled_event+ end++ # @deprecated Use {#publish_fulfillment_canceled_event}; removed in 6.1.+ def publish_shipment_canceled_event+ Spree::Deprecation.warn('Spree::Fulfillment#publish_shipment_canceled_event is deprecated and will be removed in Spree 6.1. Use #publish_fulfillment_canceled_event instead.')+ publish_fulfillment_canceled_event+ end++ # @deprecated Use {#publish_fulfillment_resumed_event}; removed in 6.1.+ def publish_shipment_resumed_event+ Spree::Deprecation.warn('Spree::Fulfillment#publish_shipment_resumed_event is deprecated and will be removed in Spree 6.1. Use #publish_fulfillment_resumed_event instead.')+ publish_fulfillment_resumed_event+ end+private- def publish_order_shipped_event+ def publish_order_fulfilled_event+ order.publish_event('order.fulfilled')+ # Legacy name — removed in 6.1order.publish_event('order.shipped')endenddiff --git a/spree/core/app/models/spree/fulfillment/webhooks.rb b/spree/core/app/models/spree/fulfillment/webhooks.rbindex af5cff1c6f..051e1bce38 100644--- a/spree/core/app/models/spree/fulfillment/webhooks.rb+++ b/spree/core/app/models/spree/fulfillment/webhooks.rb@@ -3,9 +3,15 @@ module Spreemodule Webhooksextend ActiveSupport::Concern- def send_shipment_shipped_webhook+ def send_fulfillment_fulfilled_webhook# Implement your logic hereend++ # @deprecated Use {#send_fulfillment_fulfilled_webhook}; removed in 6.1.+ def send_shipment_shipped_webhook+ Spree::Deprecation.warn('Spree::Fulfillment#send_shipment_shipped_webhook is deprecated and will be removed in Spree 6.1. Use #send_fulfillment_fulfilled_webhook instead.')+ send_fulfillment_fulfilled_webhook+ endendendenddiff --git a/spree/core/app/models/spree/fulfillment_provider/base.rb b/spree/core/app/models/spree/fulfillment_provider/base.rbnew file mode 100644index 0000000000..8408410847--- /dev/null+++ b/spree/core/app/models/spree/fulfillment_provider/base.rb@@ -0,0 +1,42 @@+module Spree+ module FulfillmentProvider+ # Strategy handling create/track/cancel mechanics per fulfillment type.+ # Stored as a string class name on DeliveryMethod, constantized at call+ # time; registered via Spree.fulfillment_providers. Replaces the legacy+ # ShipmentHandler name-constantize mechanism.+ class Base+ # @return [Boolean] whether the fulfillment may transition to fulfilled+ def can_fulfill?(_fulfillment)+ true+ end++ # Whether fulfillments handled by this provider fulfill themselves on+ # order completion (digital delivery).+ def auto_fulfill?+ false+ end++ # Performs the provider-side dispatch when a fulfillment fulfills.+ #+ # @return [Hash] optionally { tracking_number:, tracking_url: }+ def create_fulfillment(_fulfillment)+ raise NotImplementedError, "Please implement 'create_fulfillment' in your fulfillment provider: #{self.class.name}"+ end++ # Cancels the provider-side dispatch.+ def cancel_fulfillment(_fulfillment)+ raise NotImplementedError, "Please implement 'cancel_fulfillment' in your fulfillment provider: #{self.class.name}"+ end++ # @return [String, nil] provider-computed tracking URL+ def tracking_url(_fulfillment)+ nil+ end++ # @return [Array] provider documents (labels, customs forms, ...)+ def documents(_fulfillment)+ []+ end+ end+ end+enddiff --git a/spree/core/app/models/spree/fulfillment_provider/digital.rb b/spree/core/app/models/spree/fulfillment_provider/digital.rbnew file mode 100644index 0000000000..148deef3ce--- /dev/null+++ b/spree/core/app/models/spree/fulfillment_provider/digital.rb@@ -0,0 +1,36 @@+module Spree+ module FulfillmentProvider+ # Digital delivery: fulfills itself on order completion and generates+ # DigitalLinks idempotently, one per unit of quantity — replacing the+ # legacy non-idempotent checkout callback that created one link per line+ # item regardless of quantity.+ class Digital < Base+ def auto_fulfill?+ true+ end++ def create_fulfillment(fulfillment)+ fulfillment.line_items.each do |line_item|+ ensure_links_for(line_item)+ end+ {}+ end++ def cancel_fulfillment(_fulfillment)+ true+ end++ # Tops the line item up to one link per digital per unit of quantity.+ # Also used at order completion for physical items carrying digital+ # assets (e.g. vinyl + download code) that ship through other providers.+ def ensure_links_for(line_item)+ line_item.variant.digitals.each do |digital|+ existing = line_item.digital_links.where(digital: digital).count+ (line_item.quantity - existing).times do+ line_item.digital_links.create!(digital: digital)+ end+ end+ end+ end+ end+enddiff --git a/spree/core/app/models/spree/fulfillment_provider/manual.rb b/spree/core/app/models/spree/fulfillment_provider/manual.rbnew file mode 100644index 0000000000..2f184bbf7d--- /dev/null+++ b/spree/core/app/models/spree/fulfillment_provider/manual.rb@@ -0,0 +1,15 @@+module Spree+ module FulfillmentProvider+ # Default provider — admin-driven fulfillment with no provider-side+ # mechanics (tracking numbers are entered by hand).+ class Manual < Base+ def create_fulfillment(_fulfillment)+ {}+ end++ def cancel_fulfillment(_fulfillment)+ true+ end+ end+ end+enddiff --git a/spree/core/app/models/spree/fulfillment_provider/pickup.rb b/spree/core/app/models/spree/fulfillment_provider/pickup.rbnew file mode 100644index 0000000000..9571e326f2--- /dev/null+++ b/spree/core/app/models/spree/fulfillment_provider/pickup.rb@@ -0,0 +1,15 @@+module Spree+ module FulfillmentProvider+ # Merchant-location pickup: hand-over is confirmed by staff, no+ # provider-side mechanics.+ class Pickup < Base+ def create_fulfillment(_fulfillment)+ {}+ end++ def cancel_fulfillment(_fulfillment)+ true+ end+ end+ end+enddiff --git a/spree/core/app/models/spree/fulfillment_provider/pickup_point.rb b/spree/core/app/models/spree/fulfillment_provider/pickup_point.rbnew file mode 100644index 0000000000..5e86827e49--- /dev/null+++ b/spree/core/app/models/spree/fulfillment_provider/pickup_point.rb@@ -0,0 +1,16 @@+module Spree+ module FulfillmentProvider+ # Third-party pickup point (parcel locker, service point). Point+ # discovery and validation live on the delivery method's+ # PickupPointProvider; hand-over mechanics default to manual.+ class PickupPoint < Base+ def create_fulfillment(_fulfillment)+ {}+ end++ def cancel_fulfillment(_fulfillment)+ true+ end+ end+ end+enddiff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rbindex ca903a63a6..2208fb3ba8 100644--- a/spree/core/app/models/spree/order.rb+++ b/spree/core/app/models/spree/order.rb@@ -703,6 +703,8 @@ module Spreetouch :completed_at+ auto_fulfill_provider_fulfillments+send_order_placed_webhookconsider_risk@@ -809,10 +811,18 @@ module Spree%w(partial shipped fulfilled).include?(fulfillment_status)end- def fully_shipped?+ # True when every fulfillment reached the fulfilled status — the signal+ # order.fulfilled publishes on.+ def fully_fulfilled?fulfillments.fulfilled.size == fulfillments.sizeend+ # @deprecated Use {#fully_fulfilled?}; removed in 6.1.+ def fully_shipped?+ Spree::Deprecation.warn('Spree::Order#fully_shipped? is deprecated and will be removed in Spree 6.1. Use #fully_fulfilled? instead.')+ fully_fulfilled?+ end+def create_proposed_shipmentsdiscounts.for_fulfillments.delete_alltax_lines.for_fulfillments.delete_alldiff --git a/spree/core/app/models/spree/order/checkout.rb b/spree/core/app/models/spree/order/checkout.rbindex 276763ef00..f77af4ee90 100644--- a/spree/core/app/models/spree/order/checkout.rb+++ b/spree/core/app/models/spree/order/checkout.rb@@ -84,10 +84,6 @@ module Spreeendend- before_transition to: :complete do |order|- order.create_digital_links if order.with_digital_assets?- end-after_transition to: :complete, do: :create_user_recordbefore_transition to: :payment, do: :set_shipments_costbefore_transition to: :payment, do: :create_tax_charge!diff --git a/spree/core/app/models/spree/order/digital.rb b/spree/core/app/models/spree/order/digital.rbindex cbd0bae5b0..70ed9b1b17 100644--- a/spree/core/app/models/spree/order/digital.rb+++ b/spree/core/app/models/spree/order/digital.rb@@ -48,11 +48,39 @@ module Spreedigital_line_items.map(&:digital_links).flattenend+ # @deprecated DigitalLinks are created by+ # Spree::FulfillmentProvider::Digital on order completion+ # (idempotently, per quantity); removed in 6.1.def create_digital_links+ Spree::Deprecation.warn('Spree::Order#create_digital_links is deprecated and will be removed in Spree 6.1. Digital links are created by Spree::FulfillmentProvider::Digital on order completion.')+ provider = Spree::FulfillmentProvider::Digital.newdigital_line_items.includes(variant: :digitals).each do |line_item|- line_item.variant.digitals.each do |digital|- line_item.digital_links.create!(digital: digital)- end+ provider.ensure_links_for(line_item)+ end+ end++ # Fires providers that auto-fulfill on completion (digital delivery):+ # forces the fulfillment to ready and fulfills it through the machine so+ # all hooks (links, events, webhooks) run. Line items with digital+ # assets that ship through other providers (physical + download combos)+ # still get their links here, idempotently and per quantity.+ def auto_fulfill_provider_fulfillments+ handled_line_item_ids = []++ fulfillments.reload.each do |fulfillment|+ next unless fulfillment.provider.auto_fulfill?+ next if fulfillment.fulfilled? || fulfillment.canceled?++ fulfillment.update_columns(status: 'ready', updated_at: Time.current) unless fulfillment.ready?+ fulfillment.fulfill!+ handled_line_item_ids.concat(fulfillment.line_items.map(&:id))+ end++ return unless with_digital_assets?++ provider = Spree::FulfillmentProvider::Digital.new+ digital_line_items.where.not(id: handled_line_item_ids).includes(variant: :digitals).each do |line_item|+ provider.ensure_links_for(line_item)endendenddiff --git a/spree/core/app/models/spree/pickup_point_option.rb b/spree/core/app/models/spree/pickup_point_option.rbnew file mode 100644index 0000000000..cf949f0c09--- /dev/null+++ b/spree/core/app/models/spree/pickup_point_option.rb@@ -0,0 +1,23 @@+module Spree+ # Ephemeral value object returned by PickupPointProvider queries. Never+ # persisted — the selected option is frozen into+ # +fulfillment.pickup_point_data+ as plain JSON.+ PickupPointOption = Struct.new(+ :external_id,+ :name,+ :address1,+ :address2,+ :city,+ :zipcode,+ :country_iso,+ :latitude,+ :longitude,+ :provider,+ :metadata,+ keyword_init: true+ ) do+ def to_pickup_point_data+ to_h.compact.stringify_keys+ end+ end+enddiff --git a/spree/core/app/models/spree/pickup_point_provider/base.rb b/spree/core/app/models/spree/pickup_point_provider/base.rbnew file mode 100644index 0000000000..6eb06bbecc--- /dev/null+++ b/spree/core/app/models/spree/pickup_point_provider/base.rb@@ -0,0 +1,19 @@+module Spree+ module PickupPointProvider+ # Contract for third-party pickup point networks (InPost lockers, DHL+ # ServicePoints, ...). Points are ephemeral value objects — never+ # persisted; the selected point is validated via +find_by_external_id++ # and frozen into +fulfillment.pickup_point_data+.+ class Base+ # @return [Array<Spree::PickupPointOption>]+ def find_nearby(latitude:, longitude:, limit: 20)+ raise NotImplementedError, "Please implement 'find_nearby' in your pickup point provider: #{self.class.name}"+ end++ # @return [Spree::PickupPointOption, nil]+ def find_by_external_id(external_id)+ raise NotImplementedError, "Please implement 'find_by_external_id' in your pickup point provider: #{self.class.name}"+ end+ end+ end+enddiff --git a/spree/core/app/services/spree/seeds/digital_delivery.rb b/spree/core/app/services/spree/seeds/digital_delivery.rbindex d59d111489..bd52ff0c23 100644--- a/spree/core/app/services/spree/seeds/digital_delivery.rb+++ b/spree/core/app/services/spree/seeds/digital_delivery.rb@@ -8,6 +8,7 @@ module Spreedigital_delivery_method.display_on = 'both'digital_delivery_method.fulfillment_type = 'digital'+ digital_delivery_method.fulfillment_provider = 'Spree::FulfillmentProvider::Digital'digital_delivery_method.calculator ||= Spree::Calculator::Shipping::DigitalDelivery.create!digital_delivery_method.save!enddiff --git a/spree/core/lib/spree/core.rb b/spree/core/lib/spree/core.rbindex e2e03472c9..a24ecbced6 100644--- a/spree/core/lib/spree/core.rb+++ b/spree/core/lib/spree/core.rb@@ -285,6 +285,22 @@ module SpreeRails.application.config.spree.tax_provider = valueend+ def self.fulfillment_providers+ Rails.application.config.spree.fulfillment_providers+ end++ def self.fulfillment_providers=(value)+ Rails.application.config.spree.fulfillment_providers = value+ end++ def self.fulfillment_types+ Rails.application.config.spree.fulfillment_types+ end++ def self.fulfillment_types=(value)+ Rails.application.config.spree.fulfillment_types = value+ end+def self.stock_splittersRails.application.config.spree.stock_splittersenddiff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rbindex 642a98313a..97e6fa0d97 100644--- a/spree/core/lib/spree/core/engine.rb+++ b/spree/core/lib/spree/core/engine.rb@@ -11,6 +11,8 @@ module Spree:payment_methods,:adjusters,:tax_provider,+ :fulfillment_providers,+ :fulfillment_types,:stock_splitters,:order_routing,:promotions,@@ -165,6 +167,17 @@ module Spree# The sanctioned TaxLine writer (see docs/plans/6.0-tax-provider.md).Rails.application.config.spree.tax_provider = Spree::TaxProvider::Internal+ Rails.application.config.spree.fulfillment_providers = [+ Spree::FulfillmentProvider::Manual,+ Spree::FulfillmentProvider::Digital,+ Spree::FulfillmentProvider::Pickup,+ Spree::FulfillmentProvider::PickupPoint+ ]++ # Open strings, no inclusion validation — extensions append their own+ # (e.g. 'same_day_courier').+ Rails.application.config.spree.fulfillment_types = %w[shipping pickup pickup_point digital local_delivery]+# Selectable order routing strategies. The internal Reducer collaborator# is intentionally NOT listed — it is not a Strategy::Base. Plugins add# their own (or remove Legacy) via this array.diff --git a/spree/core/lib/spree/testing_support/factories/delivery_method_factory.rb b/spree/core/lib/spree/testing_support/factories/delivery_method_factory.rbindex ad64d34946..911b020e58 100644--- a/spree/core/lib/spree/testing_support/factories/delivery_method_factory.rb+++ b/spree/core/lib/spree/testing_support/factories/delivery_method_factory.rb@@ -16,6 +16,7 @@ FactoryBot.define dofactory :digital_delivery_method, aliases: [:digital_shipping_method], class: Spree::DeliveryMethod dofulfillment_type { 'digital' }+ fulfillment_provider { 'Spree::FulfillmentProvider::Digital' }association(:calculator, factory: :digital_shipping_calculator, strategy: :build)endenddiff --git a/spree/core/spec/models/spree/fulfillment/custom_events_spec.rb b/spree/core/spec/models/spree/fulfillment/custom_events_spec.rbnew file mode 100644index 0000000000..dbd5ac12f6--- /dev/null+++ b/spree/core/spec/models/spree/fulfillment/custom_events_spec.rb@@ -0,0 +1,62 @@+# frozen_string_literal: true++require 'spec_helper'++RSpec.describe Spree::Fulfillment::CustomEvents do+ let(:order) { create(:order_ready_to_ship, line_items_count: 1) }+ let(:fulfillment) { order.fulfillments.first }++ before do+ allow(Spree::Events).to receive(:enabled?).and_return(true)+ allow(Spree::Events).to receive(:publish)+ end++ describe 'fulfillment.fulfilled event' do+ it 'publishes fulfillment.fulfilled and dual-emits the legacy shipment.shipped' do+ fulfillment.fulfill!++ expect(Spree::Events).to have_received(:publish).with('fulfillment.fulfilled', anything, anything)+ expect(Spree::Events).to have_received(:publish).with('shipment.shipped', anything, anything)+ end++ it 'does not publish when events are disabled' do+ allow(Spree::Events).to receive(:enabled?).and_return(false)++ fulfillment.fulfill!++ expect(Spree::Events).not_to have_received(:publish).with('fulfillment.fulfilled', anything, anything)+ expect(Spree::Events).not_to have_received(:publish).with('shipment.shipped', anything, anything)+ end+ end++ describe 'fulfillment.canceled event' do+ it 'publishes fulfillment.canceled and dual-emits the legacy shipment.canceled' do+ fulfillment.cancel!++ expect(Spree::Events).to have_received(:publish).with('fulfillment.canceled', anything, anything)+ expect(Spree::Events).to have_received(:publish).with('shipment.canceled', anything, anything)+ end+ end++ describe 'order.fulfilled event' do+ it 'publishes order.fulfilled when the last fulfillment fulfills (plus legacy order.shipped)' do+ # The order_ready_to_ship factory creates an order with a single+ # fulfillment, so fulfilling it makes order.fully_fulfilled? true+ fulfillment.fulfill!++ expect(Spree::Events).to have_received(:publish).with('fulfillment.fulfilled', anything, anything)+ expect(Spree::Events).to have_received(:publish).with('order.fulfilled', anything, anything)+ expect(Spree::Events).to have_received(:publish).with('order.shipped', anything, anything)+ end++ it 'does not publish order.fulfilled when other fulfillments are open' do+ create(:shipment, order: order, state: 'pending')+ order.reload++ fulfillment.fulfill!++ expect(Spree::Events).to have_received(:publish).with('fulfillment.fulfilled', anything, anything)+ expect(Spree::Events).not_to have_received(:publish).with('order.fulfilled', anything, anything)+ end+ end+enddiff --git a/spree/core/spec/models/spree/fulfillment_provider/base_spec.rb b/spree/core/spec/models/spree/fulfillment_provider/base_spec.rbnew file mode 100644index 0000000000..de3eafa8a5--- /dev/null+++ b/spree/core/spec/models/spree/fulfillment_provider/base_spec.rb@@ -0,0 +1,37 @@+require 'spec_helper'++describe Spree::FulfillmentProvider::Base, type: :model do+ subject(:provider) { described_class.new }++ let(:fulfillment) { build(:fulfillment) }++ it 'allows fulfillment by default and does not auto-fulfill' do+ expect(provider.can_fulfill?(fulfillment)).to be(true)+ expect(provider.auto_fulfill?).to be(false)+ expect(provider.tracking_url(fulfillment)).to be_nil+ expect(provider.documents(fulfillment)).to eq([])+ end++ it 'requires create/cancel in subclasses' do+ expect { provider.create_fulfillment(fulfillment) }.to raise_error(NotImplementedError)+ expect { provider.cancel_fulfillment(fulfillment) }.to raise_error(NotImplementedError)+ end++ describe 'registry' do+ it 'exposes the built-in providers and fulfillment types' do+ expect(Spree.fulfillment_providers).to include(+ Spree::FulfillmentProvider::Manual,+ Spree::FulfillmentProvider::Digital,+ Spree::FulfillmentProvider::Pickup,+ Spree::FulfillmentProvider::PickupPoint+ )+ expect(Spree.fulfillment_types).to include('shipping', 'pickup', 'pickup_point', 'digital', 'local_delivery')+ end+ end++ describe 'Fulfillment#provider' do+ it 'falls back to Manual without a delivery method' do+ expect(build(:fulfillment).provider).to be_a(Spree::FulfillmentProvider::Manual)+ end+ end+enddiff --git a/spree/core/spec/models/spree/fulfillment_provider/digital_spec.rb b/spree/core/spec/models/spree/fulfillment_provider/digital_spec.rbnew file mode 100644index 0000000000..5574bc8dc5--- /dev/null+++ b/spree/core/spec/models/spree/fulfillment_provider/digital_spec.rb@@ -0,0 +1,39 @@+require 'spec_helper'++describe Spree::FulfillmentProvider::Digital, type: :model do+ subject(:provider) { described_class.new }++ it 'auto-fulfills on order completion' do+ expect(provider.auto_fulfill?).to be(true)+ end++ describe '#create_fulfillment' do+ let(:digital_product) { create(:digital_product) }+ let(:variant) { create(:variant, product: digital_product, digitals: [create(:digital), create(:digital)]) }+ let(:order) { create(:order) }+ let!(:line_item) { create(:line_item, order: order, variant: variant, quantity: 3) }+ let!(:fulfillment) { create(:fulfillment, order: order) }++ before do+ fulfillment.fulfillment_items.create!(order: order, line_item: line_item, variant: variant, quantity: 3)+ end++ it 'creates one link per digital per unit of quantity' do+ provider.create_fulfillment(fulfillment)++ expect(line_item.digital_links.reload.group(:digital_id).count.values).to eq([3, 3])+ end++ it 'is idempotent' do+ provider.create_fulfillment(fulfillment)+ expect { provider.create_fulfillment(fulfillment) }.not_to change { line_item.digital_links.reload.count }+ end++ it 'tops up missing links only' do+ provider.create_fulfillment(fulfillment)+ line_item.digital_links.reload.first.destroy!++ expect { provider.create_fulfillment(fulfillment) }.to change { line_item.digital_links.reload.count }.by(1)+ end+ end+enddiff --git a/spree/core/spec/models/spree/order/digital_auto_fulfillment_spec.rb b/spree/core/spec/models/spree/order/digital_auto_fulfillment_spec.rbnew file mode 100644index 0000000000..6d1d869b12--- /dev/null+++ b/spree/core/spec/models/spree/order/digital_auto_fulfillment_spec.rb@@ -0,0 +1,41 @@+require 'spec_helper'++describe 'Digital auto-fulfillment on order completion', type: :model do+ let(:store) { @default_store }+ let(:digital_product) { create(:digital_product, stores: [store]) }+ let(:digital_variant) { create(:variant, product: digital_product, digitals: [create(:digital)]) }+ let(:order) { create(:order_with_line_items, store: store, variants: [digital_variant], line_items_count: 1) }++ before do+ # Route the fulfillment through a digital delivery method so the provider+ # strategy resolves to Digital.+ digital_method = create(:digital_shipping_method)+ order.fulfillments.each do |fulfillment|+ rate = fulfillment.delivery_rates.create!(delivery_method: digital_method, cost: 0, selected: false)+ fulfillment.delivery_rates.where.not(id: rate.id).update_all(selected: false)+ rate.update!(selected: true)+ fulfillment.reload+ end+ end++ it 'fulfills the digital fulfillment and creates links per quantity on finalize' do+ line_item = order.line_items.first+ line_item.update_columns(quantity: 2)+ order.fulfillment_items.update_all(quantity: 2)++ order.finalize!++ fulfillment = order.fulfillments.reload.first+ expect(fulfillment).to be_fulfilled+ expect(line_item.digital_links.reload.count).to eq(2)+ expect(order.reload.fulfillment_status).to eq('fulfilled')+ end++ it 'is idempotent across repeated finalization side effects' do+ order.finalize!+ fulfillment = order.fulfillments.reload.first++ expect { fulfillment.provider.create_fulfillment(fulfillment) }.+ not_to change { Spree::DigitalLink.count }+ end+enddiff --git a/spree/core/spec/models/spree/shipment/custom_events_spec.rb b/spree/core/spec/models/spree/shipment/custom_events_spec.rbdeleted file mode 100644index 51cad69b2b..0000000000--- a/spree/core/spec/models/spree/shipment/custom_events_spec.rb+++ /dev/null@@ -1,53 +0,0 @@-# frozen_string_literal: true--require 'spec_helper'--RSpec.describe Spree::Shipment::CustomEvents do- let(:order) { create(:order_ready_to_ship, line_items_count: 1) }- let(:shipment) { order.shipments.first }-- before do- allow(Spree::Events).to receive(:enabled?).and_return(true)- allow(Spree::Events).to receive(:publish)- end-- describe 'shipment.shipped event' do- it 'publishes shipment.shipped when shipment state changes to shipped' do- allow(order).to receive(:fully_shipped?).and_return(false)-- shipment.ship!-- expect(Spree::Events).to have_received(:publish).with('shipment.shipped', anything, anything)- end-- it 'does not publish when events are disabled' do- allow(Spree::Events).to receive(:enabled?).and_return(false)-- shipment.ship!-- expect(Spree::Events).not_to have_received(:publish).with('shipment.shipped', anything, anything)- end- end-- describe 'order.shipped event' do- it 'publishes order.shipped when shipment ships and order is fully shipped' do- # The order_ready_to_ship factory creates an order with a single shipment,- # so when that shipment ships, order.fully_shipped? returns true- shipment.ship!-- expect(Spree::Events).to have_received(:publish).with('shipment.shipped', anything, anything)- expect(Spree::Events).to have_received(:publish).with('order.shipped', anything, anything)- end-- it 'does not publish order.shipped when order has unshipped shipments' do- # Create a second shipment that won't be shipped- create(:shipment, order: order, state: 'pending')- order.reload-- shipment.ship!-- expect(Spree::Events).to have_received(:publish).with('shipment.shipped', anything, anything)- expect(Spree::Events).not_to have_received(:publish).with('order.shipped', anything, anything)- end- end-end