Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.md
index 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.rb
index 363060c7a3..b3282c262b 100644
--- a/spree/core/app/models/spree/fulfillment.rb
+++ b/spree/core/app/models/spree/fulfillment.rb
@@ -100,14 +100,15 @@ module Spree
end
event :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 do
transition 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 do
transition from: :canceled, to: :ready, if: lambda { |fulfillment|
@@ -115,7 +116,7 @@ module Spree
}
transition from: :canceled, to: :pending
end
- 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 Spree
def after_cancel
manifest.each { |item| manifest_restock(item) }
+ provider.cancel_fulfillment(self)
end
def after_resume
@@ -490,6 +492,23 @@ module Spree
selected_delivery_rate&.delivery_method || delivery_rates.first&.delivery_method
end
+ # 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 Spree
fulfillment_items.each(&:ship!)
process_order_payments if Spree::Config[:auto_capture_on_dispatch]
touch :fulfilled_at
+ run_provider_create_fulfillment
update_order_fulfillment_status
end
+ # 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_status
new_status = OrderUpdater.new(order).update_fulfillment_status
order.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.rb
index 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 Spree
class 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 CustomEvents
extend 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_event
return unless Spree::Events.enabled?
+ publish_event('fulfillment.fulfilled')
+ # Legacy name — removed in 6.1
publish_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_event
return unless Spree::Events.enabled?
+ publish_event('fulfillment.canceled')
+ # Legacy name — removed in 6.1
publish_event('shipment.canceled')
end
- def publish_shipment_resumed_event
+ def publish_fulfillment_resumed_event
return unless Spree::Events.enabled?
+ publish_event('fulfillment.resumed')
+ # Legacy name — removed in 6.1
publish_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.1
order.publish_event('order.shipped')
end
end
diff --git a/spree/core/app/models/spree/fulfillment/webhooks.rb b/spree/core/app/models/spree/fulfillment/webhooks.rb
index 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 Spree
module Webhooks
extend ActiveSupport::Concern
- def send_shipment_shipped_webhook
+ def send_fulfillment_fulfilled_webhook
# Implement your logic here
end
+
+ # @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
+ end
end
end
end
diff --git a/spree/core/app/models/spree/fulfillment_provider/base.rb b/spree/core/app/models/spree/fulfillment_provider/base.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/models/spree/fulfillment_provider/digital.rb b/spree/core/app/models/spree/fulfillment_provider/digital.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/models/spree/fulfillment_provider/manual.rb b/spree/core/app/models/spree/fulfillment_provider/manual.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/models/spree/fulfillment_provider/pickup.rb b/spree/core/app/models/spree/fulfillment_provider/pickup.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/models/spree/fulfillment_provider/pickup_point.rb b/spree/core/app/models/spree/fulfillment_provider/pickup_point.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index ca903a63a6..2208fb3ba8 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -703,6 +703,8 @@ module Spree
touch :completed_at
+ auto_fulfill_provider_fulfillments
+
send_order_placed_webhook
consider_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.size
end
+ # @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_shipments
discounts.for_fulfillments.delete_all
tax_lines.for_fulfillments.delete_all
diff --git a/spree/core/app/models/spree/order/checkout.rb b/spree/core/app/models/spree/order/checkout.rb
index 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 Spree
end
end
- before_transition to: :complete do |order|
- order.create_digital_links if order.with_digital_assets?
- end
-
after_transition to: :complete, do: :create_user_record
before_transition to: :payment, do: :set_shipments_cost
before_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.rb
index 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 Spree
digital_line_items.map(&:digital_links).flatten
end
+ # @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.new
digital_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)
end
end
end
diff --git a/spree/core/app/models/spree/pickup_point_option.rb b/spree/core/app/models/spree/pickup_point_option.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/models/spree/pickup_point_provider/base.rb b/spree/core/app/models/spree/pickup_point_provider/base.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/services/spree/seeds/digital_delivery.rb b/spree/core/app/services/spree/seeds/digital_delivery.rb
index 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 Spree
digital_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!
end
diff --git a/spree/core/lib/spree/core.rb b/spree/core/lib/spree/core.rb
index e2e03472c9..a24ecbced6 100644
--- a/spree/core/lib/spree/core.rb
+++ b/spree/core/lib/spree/core.rb
@@ -285,6 +285,22 @@ module Spree
Rails.application.config.spree.tax_provider = value
end
+ 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_splitters
Rails.application.config.spree.stock_splitters
end
diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rb
index 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.rb
index 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 do
factory :digital_delivery_method, aliases: [:digital_shipping_method], class: Spree::DeliveryMethod do
fulfillment_type { 'digital' }
+ fulfillment_provider { 'Spree::FulfillmentProvider::Digital' }
association(:calculator, factory: :digital_shipping_calculator, strategy: :build)
end
end
diff --git a/spree/core/spec/models/spree/fulfillment/custom_events_spec.rb b/spree/core/spec/models/spree/fulfillment/custom_events_spec.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/spec/models/spree/fulfillment_provider/base_spec.rb b/spree/core/spec/models/spree/fulfillment_provider/base_spec.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/spec/models/spree/fulfillment_provider/digital_spec.rb b/spree/core/spec/models/spree/fulfillment_provider/digital_spec.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/spec/models/spree/order/digital_auto_fulfillment_spec.rb b/spree/core/spec/models/spree/order/digital_auto_fulfillment_spec.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/spec/models/spree/shipment/custom_events_spec.rb b/spree/core/spec/models/spree/shipment/custom_events_spec.rb
deleted file mode 100644
index 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