spree_core 5.6.0 → 6.0.0.beta1

data/app/workflows/spree/customers/create.rb

@@ -0,0 +1,247 @@
+module Spree
+  module Customers
+    # Creates a customer account — the single storefront registration flow
+    # (docs/plans/6.0-service-workflows.md decision 13).
+    #
+    # Two callers today: store self-registration and the checkout "create an
+    # account" box, which passes `order:` — the customer is built from the
+    # order without a password (the account is claimed via password reset,
+    # like an admin-created one), the order's addresses become the account's
+    # defaults and the order is linked to the new account.
+    #
+    # The `validate` hook is the veto seam for registration policy —
+    # bot/disposable-email screening, fraud checks, B2B approval. Handlers
+    # read the built (unsaved) `customer` plus `order`/`created_by`; staff
+    # bypass is a handler decision via `created_by`, the same pattern as
+    # return eligibility. Core sends no welcome email — signup email is
+    # host-app code on the `user.created` event or the `after_create` hook.
+    class Create < Spree::Workflow
+      hooks :validate, :after_create
+
+      # The customer record — built (unsaved) while :validate runs.
+      attr_reader :customer
+
+      # @param store [Spree::Store] the store the registration happens on;
+      #   exposed to hook handlers and scopes the newsletter-subscriber link
+      # @param email [String, nil] defaults to the order email with `order:`
+      # @param password [String, nil]
+      # @param password_confirmation [String, nil]
+      # @param first_name [String, nil] defaults from the order addresses
+      #   with `order:`, as do last_name and phone
+      # @param last_name [String, nil]
+      # @param phone [String, nil]
+      # @param accepts_email_marketing [Boolean, nil] defaults from the
+      #   order's marketing opt-in with `order:`
+      # @param metadata [Hash, nil]
+      # @param order [Spree::Order, nil] a placed order adopting the new
+      #   account; when its email already belongs to a customer, the order is
+      #   linked to that account and no new customer is created
+      # @param password_required [Boolean, nil] whether a missing password
+      #   fails the registration (the account is created password-less
+      #   otherwise and claimed via password reset). Defaults to true except
+      #   with `order:` — guest checkout collects no password, while
+      #   self-registration must, because the caller issues a JWT on success
+      # @param terms_of_service [Boolean, nil] whether the person ticked the
+      #   storefront's terms box. Only a true value records a terms consent
+      #   row — absent means "not asked", which is not agreement
+      # @param created_by [Object, nil] the staff actor; nil for storefront
+      #   self-registration
+      def perform(store:, email: nil, password: nil, password_confirmation: nil,
+                  first_name: nil, last_name: nil, phone: nil,
+                  accepts_email_marketing: nil, metadata: nil,
+                  order: nil, password_required: nil, created_by: nil,
+                  terms_of_service: nil, ip_address: nil, user_agent: nil)
+        super
+
+        step :adopt_existing_customer
+        step :build_customer
+        step :ensure_password
+
+        # Veto point — registration policy. The customer is built but not
+        # yet persisted.
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :create_customer
+          step :link_order
+          step :record_consent
+        end
+
+        step :link_newsletter_subscriber
+        run_hooks :after_create
+        success(order ? customer.reload : customer)
+      end
+
+      private
+
+      # Checkout only: an account with the order's email already exists, so
+      # the order joins it instead of registering a duplicate. Registration
+      # policy hooks don't run — nothing is being registered.
+      def adopt_existing_customer
+        return unless order
+
+        existing_customer = Spree.customer_class.find_by(email: order.email)
+        return unless existing_customer
+
+        assign_order_to(existing_customer)
+        halt!(existing_customer)
+      end
+
+      def build_customer
+        @customer = Spree.customer_class.new(customer_attributes)
+      end
+
+      def customer_attributes
+        order_address = order && (order.bill_address || order.ship_address)
+
+        {
+          email: email || order&.email,
+          password: password,
+          password_confirmation: password_confirmation,
+          first_name: first_name || order_address&.first_name,
+          last_name: last_name || order_address&.last_name,
+          phone: phone || order_address&.phone,
+          accepts_email_marketing: accepts_email_marketing.nil? ? order&.accept_marketing? : accepts_email_marketing,
+          metadata: metadata
+        }.compact
+      end
+
+      # The model itself allows a blank password — a password-less account
+      # cannot log in (Customer#valid_password? guards the blank digest) and
+      # is claimed via password reset; whether registration accepts that
+      # state is the password_required policy. No password is generated:
+      # blank is the one unclaimed-account state everywhere, and a generated
+      # value could fail a host's swapped-in Spree.password_validator.
+      def ensure_password
+        return if customer.password.present? || !password_required?
+
+        customer.errors.add(:password, :blank)
+        failure(customer)
+      end
+
+      def password_required?
+        password_required.nil? ? order.nil? : password_required
+      end
+
+      def create_customer
+        # Keeps the stamped column agreeing with the consent row written below
+        # — otherwise a registration records 'registration' in one place and
+        # 'account' in the other, for the same instant.
+        customer.consent_source = consent_source
+        failure(customer) unless customer.save
+      end
+
+      # Records what the person actually agreed to.
+      #
+      # Terms are recorded only when the caller says the box was ticked. A row
+      # written for every registration would be fabricated evidence: the
+      # checkout account box presents no terms checkbox at all, and a consent
+      # record is worth having precisely because it is not assumed.
+      #
+      # Inside the transaction: a customer that exists without the record of
+      # what they agreed to is exactly the gap these rows are meant to close.
+      def record_consent
+        if accepted_terms?
+          Spree::ConsentRecord.record!(
+            store: store,
+            owner: customer,
+            purpose: Spree::ConsentRecord::TERMS_OF_SERVICE,
+            source: consent_source,
+            email: customer.email,
+            ip_address: ip_address,
+            user_agent: user_agent,
+            policies: consent_policies
+          )
+        end
+
+        # Checkout already recorded the marketing opt-in against the order
+        # before this workflow ran (OrderPlacedSubscriber), so writing one here
+        # too would make a single tick look like two separate agreements.
+        return if order
+        return unless customer.accepts_email_marketing?
+
+        Spree::ConsentRecord.record!(
+          store: store,
+          owner: customer,
+          purpose: Spree::ConsentRecord::EMAIL_MARKETING,
+          source: consent_source,
+          email: customer.email,
+          ip_address: ip_address,
+          user_agent: user_agent
+        )
+      end
+
+      # The storefront passes `terms_of_service` when its consent box is
+      # ticked. Absent means "not asked", which is not the same as agreed.
+      def accepted_terms?
+        ActiveModel::Type::Boolean.new.cast(terms_of_service).present?
+      end
+
+      # An account created from a placed order was agreed to at checkout; one
+      # created directly was agreed to at registration.
+      def consent_source
+        order ? Spree::ConsentRecord::CHECKOUT : Spree::ConsentRecord::REGISTRATION
+      end
+
+      # The documents as they read at the moment of agreement, so a merchant
+      # who later edits their terms can still show which text this person saw.
+      # The document the tick was next to, not every policy the store keeps.
+      # A consent row exists to prove which text somebody accepted, so naming
+      # the returns and shipping policies beside it — which no checkbox showed
+      # — is the same fabricated evidence as recording a terms agreement for
+      # an account that was never asked for one.
+      #
+      # Matched by name because policies are an open set with no fixed
+      # vocabulary: a store may not have one called "Terms of Service", and
+      # then there is nothing to snapshot rather than something to guess at.
+      def consent_policies
+        store.policies.with_matching_name(Spree.t(:terms_of_service)).to_a
+      end
+
+      def link_order
+        return unless order
+
+        adopt_addresses
+        assign_order_to(customer)
+      end
+
+      # The order's addresses become the new account's defaults — but only
+      # unowned ones: an address already in another customer's address book
+      # must not be re-homed onto the new account.
+      # update_columns because the order is already placed and the address
+      # already validated — re-running validations here could reject a
+      # linkage the checkout accepted.
+      def adopt_addresses
+        addresses = { bill_address_id: order.bill_address, ship_address_id: order.ship_address }.
+          select { |_, address| address.present? && address.owner_id.nil? }
+        return if addresses.empty?
+
+        addresses.values.uniq.each do |address|
+          address.update_columns(owner_type: Spree.customer_class.to_s, owner_id: customer.id, updated_at: Time.current)
+        end
+
+        customer.update_columns(addresses.transform_values(&:id).merge(updated_at: Time.current))
+      end
+
+      # Only the customer link is written. Deliberately NOT
+      # Order#associate_customer! — that backfills the cart's missing
+      # addresses from the customer's address book, which on an order the
+      # buyer already placed would rewrite historical data. The event is
+      # published by hand for the same reason Carts::Associate does it:
+      # update_columns bypasses callbacks.
+      def assign_order_to(account)
+        order.update_columns(customer_id: account.id, updated_at: Time.current)
+        order.customer = account
+        order.publish_event("#{order.event_prefix}.updated")
+      end
+
+      # Someone who subscribed to the newsletter before registering gets their
+      # subscription linked to the new account, with verified opt-in carried
+      # over. Best-effort by design — see Spree::Newsletter::LinkUser.
+      def link_newsletter_subscriber
+        subscriber = Spree::NewsletterSubscriber.find_by(email: customer.email, store: store)
+        Spree::Newsletter::LinkUser.new(subscriber: subscriber, user: customer).call
+      end
+    end
+  end
+end

data/app/workflows/spree/data_requests/fulfill.rb

@@ -0,0 +1,165 @@
+module Spree
+  module DataRequests
+    # Carries out a data subject request: builds and attaches the export for
+    # an access request, runs the anonymizer for an erasure request.
+    #
+    # In the workflow tier for its hooks — a host app that must include data
+    # Spree does not model (a loyalty ledger, a support-ticket history) adds
+    # it to the payload here, and that is the only place where the shape of a
+    # subject access response can be completed.
+    #
+    # Marking a request `failed` is the caller's job, not this flow's: see
+    # {Spree::DataRequests::ProcessJob}. A workflow cannot rescue around its
+    # own steps, because FailureSignal and Halted descend from Exception and
+    # rescuing swallows the result the caller is waiting for.
+    class Fulfill < Spree::Workflow
+      hooks :before_fulfill, :extend_payload, :after_fulfill
+
+      # Builds the payload for a request, hook included.
+      #
+      # Exposed as a class method because the admin export renders inline for a
+      # staffer who is waiting, rather than going through the queued flow — and
+      # an Art. 15 response assembled without the extension point would omit
+      # exactly the host-app data the hook exists to attach. Both paths build
+      # the same document.
+      #
+      # @param data_request [Spree::DataRequest]
+      # @return [Hash]
+      def self.payload_for(data_request)
+        new.send(:export_payload, data_request)
+      end
+
+
+      # @param data_request [Spree::DataRequest]
+      # @return [Spree::ServiceModule::Result] the fulfilled request
+      def perform(data_request:)
+        super
+
+        step :ensure_pending
+        step :mark_processing
+
+        run_hooks :before_fulfill
+
+        step :fulfill_request
+        step :mark_completed
+
+        run_hooks :after_fulfill
+
+        success(data_request.reload)
+      end
+
+      private
+
+      def ensure_pending
+        return if data_request.pending?
+
+        failure(data_request, Spree.t('data_request_errors.not_pending'))
+      end
+
+      def mark_processing
+        data_request.update!(status: 'processing')
+      end
+
+      def fulfill_request
+        data_request.access? ? build_export : erase_customer
+      end
+
+      def build_export
+        customer = data_request.customer
+
+        # An erasure can land while this sits in the queue. Answering now would
+        # write a file into private storage for someone who asked to be
+        # forgotten — redacted, and behind a token the erasure already cleared,
+        # so nobody could open it, but a file about them all the same and a
+        # request they can never collect. Refusing says what happened.
+        #
+        # Read and attach under the customer's row lock, which is the same lock
+        # the erasure takes: checking without it leaves a window where the
+        # anonymizer starts after the check and finishes its attachment scan
+        # before this attaches, stranding a full personal-data file it will
+        # never see.
+        return attach_export unless customer
+
+        refused = false
+
+        customer.with_lock do
+          if customer.reload.anonymized?
+            refused = true
+          else
+            attach_export
+          end
+        end
+
+        return unless refused
+
+        failure(data_request, Spree.t('data_request_errors.already_anonymized'))
+      end
+
+      def attach_export
+        payload = export_payload(data_request)
+
+        data_request.export_file.attach(
+          io: StringIO.new(JSON.pretty_generate(payload)),
+          filename: "#{data_request.number.downcase}.json",
+          content_type: 'application/json'
+        )
+        data_request.expires_at = Spree::DataRequest::DEFAULT_EXPIRY.from_now
+      end
+
+      # The document itself.
+      #
+      # Binds `data_request` through the workflow's own argument mechanism, so
+      # a hook handler reads the same `workflow.data_request` it does in the
+      # queued flow rather than a reader that happens to exist.
+      #
+      # @param request [Spree::DataRequest]
+      # @return [Hash]
+      def export_payload(request)
+        @data_request = request
+        self.class.define_argument_readers([:data_request])
+
+        payload = Spree.customer_data_export_service.new(
+          customer: request.customer,
+          store: request.store
+        ).call
+
+        # The extension point for data Spree does not model. Handlers return a
+        # hash, which run_hooks deep-merges — so a host app adds its own keys
+        # without being able to silently drop Spree's.
+        payload.deep_merge(run_hooks(:extend_payload).presence || {})
+      end
+
+      def erase_customer
+        customer = data_request.customer
+
+        # Already erased is the outcome this request asked for, however it came
+        # about — staff may have run it while this job sat in the queue, or the
+        # person may have asked twice. Recording that as a failure would leave
+        # someone whose data IS gone holding a failed request, and a failed
+        # request is what stops them opening another.
+        return if customer.anonymized?
+
+        result = Spree.customer_anonymize_workflow.call(
+          customer: customer,
+          store: data_request.store,
+          requested_by: data_request.requested_by
+        )
+
+        return if result.success?
+
+        # The erasure can also be refused because a concurrent one claimed the
+        # account after the check above — the two are not distinguishable from
+        # the refusal itself, so the state is what answers. Only a person who
+        # is still identified represents a request this flow failed to serve.
+        return if customer.reload.anonymized?
+
+        failure(data_request, result.error.to_s)
+      end
+
+      def mark_completed
+        data_request.update!(status: 'completed', completed_at: Time.current)
+        data_request.publish_event('data_request.completed')
+      end
+    end
+  end
+end

data/app/workflows/spree/deliveries/update_tracking.rb

@@ -0,0 +1,96 @@
+module Spree
+  module Deliveries
+    # Records what the carrier says about one consignment in flight.
+    #
+    # This is the carrier axis: it never moves the owner backwards and never
+    # contradicts the merchant. A parcel that bounces or is damaged shows up
+    # here as `return_to_sender` or `failure` while the fulfillment still
+    # says `fulfilled` — the merchant did hand it over. The one status that
+    # crosses over is `delivered`: when every delivery of a fulfillment has
+    # arrived, the fulfillment is marked delivered through
+    # Spree::Fulfillments::MarkDelivered. A Return owner never transitions —
+    # goods arriving is not goods inspected, and Spree::Returns::Receive stays
+    # a staff act; anything that wants to react hangs on
+    # +after_update_tracking+.
+    #
+    # Providers call this from their webhook handlers, so it accepts the
+    # already-normalized vocabulary rather than any carrier's raw payload:
+    # translating a provider's status names is the provider gem's job.
+    class UpdateTracking < Spree::Workflow
+      hooks :validate, :after_update_tracking
+
+      # @param delivery [Spree::Delivery] the consignment being tracked
+      # @param tracking_status [String, nil] one of {Spree::Delivery::STATUSES}
+      # @param estimated_delivery_at [Time, nil] carrier's current estimate
+      # @param delivered_at [Time, nil] when the carrier says it arrived; used
+      #   only when +tracking_status+ is `delivered`, defaulting to now
+      # @param details [Hash, nil] provider payload worth keeping — scan events,
+      #   the signature, the failure reason
+      # @param notify_customer [Boolean] passed through to MarkDelivered when
+      #   this update completes the fulfillment's delivery
+      # @return [Spree::ServiceModule::Result] the updated delivery on success
+      def perform(delivery:, tracking_status: nil, estimated_delivery_at: nil, delivered_at: nil,
+                  details: nil, notify_customer: true)
+        super
+
+        run_hooks :validate
+
+        step :ensure_known_status
+        step :apply_carrier_report
+        step :roll_up_owner_delivery
+
+        run_hooks :after_update_tracking
+        success(delivery.reload)
+      end
+
+      private
+
+      def ensure_known_status
+        return if tracking_status.blank?
+        return if Spree::Delivery::STATUSES.include?(tracking_status.to_s)
+
+        failure(delivery, Spree.t('fulfillments.errors.unknown_tracking_status', status: tracking_status))
+      end
+
+      # Overwrite rather than accumulate: this axis answers "where is it now",
+      # and carriers resend the whole picture on every update. Only attributes
+      # the caller actually supplied are touched, so a webhook carrying just a
+      # scan does not wipe an estimate from an earlier one.
+      def apply_carrier_report
+        attributes = {}
+        attributes[:status] = tracking_status.to_s if tracking_status.present?
+        attributes[:estimated_delivery_at] = estimated_delivery_at unless estimated_delivery_at.nil?
+        attributes[:details] = details unless details.nil?
+        attributes[:delivered_at] = delivered_at || delivery.delivered_at || Time.current if reported_delivered?
+
+        return if attributes.empty?
+
+        # update_columns, deliberately: carrier scans arrive many times per
+        # parcel, and a lifecycle event per scan would run the full order
+        # status rollup for writes that cannot change any status. The
+        # after_update_tracking hook and the fulfillment.delivered event are
+        # the notification surface for this axis.
+        delivery.update_columns(attributes.merge(updated_at: Time.current))
+      end
+
+      # Arrival is the one carrier report that is also a merchant fact, so it
+      # crosses over to the fulfillment's status — once every consignment has
+      # arrived. A Return owner never transitions: goods coming back is not
+      # goods inspected.
+      def roll_up_owner_delivery
+        owner = delivery.owner
+        return unless owner.is_a?(Spree::Fulfillment)
+
+        result = Spree.fulfillment_recalculate_delivery_service.call(
+          fulfillment: owner, notify_customer: notify_customer
+        )
+
+        failure(delivery, result.error.to_s) if result.failure?
+      end
+
+      def reported_delivered?
+        tracking_status.to_s == 'delivered'
+      end
+    end
+  end
+end

data/app/workflows/spree/exchanges/approve.rb

@@ -0,0 +1,38 @@
+module Spree
+  module Exchanges
+    class Approve < Spree::Workflow
+      hooks :validate, :after_approve
+
+      # @param exchange [Spree::Exchange]
+      # @param approver [Object, nil]
+      def perform(exchange:, approver: nil)
+        super
+
+        step :ensure_approvable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_approved
+        end
+
+        run_hooks :after_approve
+        exchange.publish_event('exchange.approved')
+        success(exchange.reload)
+      end
+
+      private
+
+      def ensure_approvable
+        failure(exchange, :not_requested) unless exchange.requested?
+      end
+
+      def mark_approved
+        exchange.update!(
+          status: 'approved',
+          approved_at: Time.current,
+          created_by: exchange.created_by || approver
+        )
+      end
+    end
+  end
+end

data/app/workflows/spree/exchanges/cancel.rb

@@ -0,0 +1,40 @@
+module Spree
+  module Exchanges
+    # Withdraws an exchange before the goods arrive. Once received, the
+    # merchant holds the customer's items and must either fulfill the
+    # replacement or refund.
+    class Cancel < Spree::Workflow
+      hooks :validate, :after_cancel
+
+      # @param exchange [Spree::Exchange]
+      # @param reason [String, nil]
+      def perform(exchange:, reason: nil)
+        super
+
+        step :ensure_cancellable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_canceled
+        end
+
+        run_hooks :after_cancel
+        exchange.publish_event('exchange.canceled')
+        success(exchange.reload)
+      end
+
+      private
+
+      def ensure_cancellable
+        return if exchange.requested? || exchange.approved?
+
+        failure(exchange, :not_cancellable)
+      end
+
+      def mark_canceled
+        memo = [exchange.memo, reason].compact_blank.join("\n")
+        exchange.update!(status: 'canceled', canceled_at: Time.current, memo: memo.presence)
+      end
+    end
+  end
+end

data/app/workflows/spree/exchanges/create.rb

@@ -0,0 +1,90 @@
+module Spree
+  module Exchanges
+    # Opens an exchange request: items coming back, and what should go out
+    # in their place.
+    class Create < Spree::Workflow
+      hooks :validate, :after_create
+
+      attr_reader :exchange
+
+      # @param order [Spree::Order]
+      # @param items [Array<Hash>] `[{ fulfillment_item:, new_variant:, quantity: }]`
+      # @param stock_location [Spree::StockLocation, nil]
+      # @param reason [Spree::ReturnReason, nil]
+      # @param memo [String, nil]
+      # @param created_by [Object, nil] nil for customer self-service
+      def perform(order:, items:, stock_location: nil, reason: nil, memo: nil, created_by: nil)
+        super
+
+        step :ensure_exchangeable
+        step :normalize_items
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :build_exchange
+        end
+
+        run_hooks :after_create
+        exchange.publish_event('exchange.requested')
+        success(exchange.reload)
+      end
+
+      private
+
+      def ensure_exchangeable
+        failure(order, :order_not_completed) unless order.completed?
+        failure(order, :order_canceled) if order.canceled?
+        failure(order, :no_items_to_exchange) if items.blank?
+      end
+
+      def normalize_items
+        @normalized_items = items.map do |item|
+          fulfillment_item = item[:fulfillment_item]
+          new_variant = item[:new_variant]
+          quantity = item[:quantity].to_i
+
+          failure(order, :invalid_quantity) unless quantity.positive?
+          failure(order, :item_not_on_order) unless fulfillment_item&.order_id == order.id
+          failure(order, :replacement_required) if new_variant.blank?
+
+          # A replacement nobody can ship is not an exchange the merchant can
+          # honour — catch it now rather than at fulfillment time.
+          unless new_variant.purchasable?
+            failure(order, "#{new_variant.name} is not available")
+          end
+
+          { fulfillment_item: fulfillment_item, new_variant: new_variant, quantity: quantity }
+        end
+      end
+
+      def build_exchange
+        @exchange = order.exchanges.new(
+          store: order.store,
+          stock_location: stock_location || default_stock_location,
+          reason: reason,
+          memo: memo,
+          created_by: created_by,
+          status: Spree::Exchange.default_status
+        )
+
+        @normalized_items.each do |item|
+          fulfillment_item = item[:fulfillment_item]
+          @exchange.exchange_line_items.build(
+            fulfillment_item: fulfillment_item,
+            line_item: fulfillment_item.line_item,
+            original_variant: fulfillment_item.variant,
+            new_variant: item[:new_variant],
+            quantity: item[:quantity]
+          )
+        end
+
+        failure(@exchange) unless @exchange.save
+      end
+
+      def default_stock_location
+        @normalized_items.first[:fulfillment_item].fulfillment&.stock_location ||
+          order.store.stock_locations.first
+      end
+    end
+  end
+end