spree_core 5.6.1 → 6.0.0.beta1

data/app/services/spree/customers/data_export.rb

@@ -0,0 +1,372 @@
+module Spree
+  module Customers
+    # Assembles everything a store holds about one person, for GDPR Art. 15
+    # (right of access) and Art. 20 (portability).
+    #
+    # Art. 20 asks for a "structured, commonly used and machine-readable"
+    # format, which is why this returns a plain hash destined for JSON rather
+    # than the CSV the admin exports use — a customer's data is nested, and
+    # flattening orders and their line items into a spreadsheet loses the
+    # structure the regulation asks to preserve.
+    #
+    # Read-only and side-effect free: the caller decides whether the result is
+    # streamed, written to a file or attached to a request record.
+    class DataExport
+      include Spree::PersonalDataMatching
+
+      # @param customer [Spree::Customer]
+      # @param store [Spree::Store, nil] the store the request came in through,
+      #   recorded on the request rather than used to narrow this payload.
+      #   Nothing here is scoped to one store: erasure never is, and an access
+      #   response that showed less than the erasure removes would understate
+      #   what the controller holds. Kept for host apps that override this
+      #   service and for the sections a multi-store build may want to label.
+      def initialize(customer:, store: nil)
+        @customer = customer
+        @store = store
+      end
+
+      # @return [Hash]
+      def call
+        {
+          account: account,
+          marketing_consent: marketing_consent,
+          consent_records: consent_records,
+          addresses: addresses,
+          orders: orders,
+          draft_orders: draft_orders,
+          order_groups: order_groups,
+          carts: carts,
+          payment_sources: payment_sources,
+          connected_logins: connected_logins,
+          store_credits: store_credits,
+          gift_cards: gift_cards,
+          wishlists: wishlists,
+          custom_fields: custom_fields,
+          companies: companies,
+          tax_identifiers: tax_identifiers,
+          exported_at: Time.current.iso8601
+        }
+      end
+
+      private
+
+      attr_reader :customer, :store
+
+      def account
+        {
+          id: customer.prefixed_id,
+          email: customer.email,
+          first_name: customer.first_name,
+          last_name: customer.last_name,
+          phone: customer.phone,
+          selected_locale: customer.selected_locale,
+          tags: customer.tag_list.to_a,
+          metadata: customer.metadata.presence,
+          internal_note: customer.internal_note,
+          created_at: customer.created_at&.iso8601,
+          anonymized_at: customer.anonymized_at&.iso8601
+        }
+      end
+
+      def marketing_consent
+        {
+          accepts_email_marketing: customer.accepts_email_marketing,
+          consent_updated_at: customer.email_marketing_consent_updated_at&.iso8601,
+          consent_source: customer.email_marketing_consent_source,
+          newsletter_subscriptions: newsletter_subscriptions
+        }
+      end
+
+      # Matched by email as well as by customer, mirroring the anonymizer: a
+      # guest sign-up carries no customer id, and an access response that
+      # skipped it would omit data the store holds and is about to wipe.
+      # Never narrowed to one store — erasure removes these rows everywhere.
+      def newsletter_subscriptions
+        personal_newsletter_subscribers(customer, email: customer.email).map do |subscriber|
+          {
+            email: subscriber.email,
+            verified_at: subscriber.verified_at&.iso8601,
+            created_at: subscriber.created_at&.iso8601
+          }
+        end
+      end
+
+      # The evidence trail behind the booleans above — when each agreement was
+      # made, from where, and which document version was shown.
+      # Matched by email as well as by owner: guest checkout records consent
+      # against the ORDER, so a person who bought before registering has rows
+      # that are about them but which this account does not own.
+      def consent_records
+        personal_consent_records(customer, email: customer.email).recent_first.map do |record|
+          {
+            purpose: record.purpose,
+            source: record.source,
+            accepted: record.accepted,
+            email: record.email,
+            ip_address: record.ip_address,
+            user_agent: record.user_agent,
+            recorded_at: record.recorded_at&.iso8601,
+            documents: record.documents_list
+          }
+        end
+      end
+
+      # Reads the table rather than `customer.addresses`, which hides
+      # soft-deleted rows. An address the person removed is still an address
+      # this store holds, and erasure reaches it — so an access response that
+      # skipped it would understate what is on file.
+      def addresses
+        Spree::Address.
+          where(owner_type: customer.class.base_class.to_s, owner_id: customer.id).
+          map { |address| address_hash(address) }
+      end
+
+      # Batched: a long-standing customer's whole order history, its line items
+      # and both address snapshots would otherwise be resident at once, beside
+      # the hash built from them and the JSON built from that.
+      def orders
+        exported = []
+
+        owned_purchases(Spree::Order).complete.with_attached_po_document.
+          includes(:bill_address, :ship_address, line_items: { variant: :product }).find_each do |order|
+          exported << {
+            number: order.number,
+            email: order.email,
+            currency: order.currency,
+            item_total: order.item_total&.to_s,
+            total: order.total&.to_s,
+            payment_status: order.payment_status,
+            fulfillment_status: order.fulfillment_status,
+            completed_at: order.completed_at&.iso8601,
+            customer_note: order.customer_note,
+            po_number: order.po_number,
+            po_document: order.po_document.attached? ? order.po_document.filename.to_s : nil,
+            last_ip_address: order.last_ip_address,
+            metadata: order.metadata.presence,
+            internal_note: order.internal_note,
+            billing_address: address_hash(order.bill_address),
+            shipping_address: address_hash(order.ship_address),
+            line_items: order.line_items.map do |line_item|
+              {
+                name: line_item.name,
+                sku: line_item.sku,
+                quantity: line_item.quantity,
+                price: line_item.price&.to_s,
+                total: line_item.total&.to_s,
+                currency: line_item.currency
+              }
+            end
+          }
+        end
+
+        exported
+      end
+
+      # A checkout split across sellers becomes one order per seller under a
+      # group, and the group keeps its own copy of where the whole thing was
+      # going.
+      def order_groups
+        owned_purchases(Spree::OrderGroup).
+          includes(:bill_address, :ship_address).map do |group|
+          {
+            number: group.number,
+            email: group.email,
+            currency: group.currency,
+            metadata: group.metadata.presence,
+            billing_address: address_hash(group.bill_address),
+            shipping_address: address_hash(group.ship_address),
+            created_at: group.created_at&.iso8601
+          }
+        end
+      end
+
+      # An order a staff member started for this person but never placed. It is
+      # not an abandoned checkout — those are carts, on their own table — and
+      # it holds the same personal data a placed order does.
+      def draft_orders
+        unplaced_purchases(owned_purchases(Spree::Order).incomplete) do |order|
+          { number: order.number, internal_note: order.internal_note }
+        end
+      end
+
+      # Abandoned checkouts are retained data about this person, so an access
+      # request has to disclose them. Kept separate from orders: nothing was
+      # bought, and listing them together would misrepresent both.
+      def carts
+        unplaced_purchases(owned_purchases(Spree::Cart))
+      end
+
+      # Drafts and abandoned carts disclose the same fields; the caller adds
+      # whatever its own model carries on top. Batched for the same reason
+      # #orders is.
+      def unplaced_purchases(relation)
+        exported = []
+
+        relation.includes(:bill_address, :ship_address, line_items: { variant: :product }).
+          find_each do |purchase|
+          extra = block_given? ? yield(purchase) : {}
+
+          exported << {
+            email: purchase.email,
+            currency: purchase.currency,
+            item_total: purchase.item_total&.to_s,
+            customer_note: purchase.customer_note,
+            last_ip_address: purchase.last_ip_address,
+            metadata: purchase.metadata.presence,
+            billing_address: address_hash(purchase.bill_address),
+            shipping_address: address_hash(purchase.ship_address),
+            created_at: purchase.created_at&.iso8601,
+            line_items: purchase.line_items.map do |line_item|
+              { name: line_item.name, sku: line_item.sku, quantity: line_item.quantity }
+            end
+          }.merge(extra)
+        end
+
+        exported
+      end
+
+      # Card numbers were never stored, so this is the metadata that was: the
+      # brand, the last four digits and the expiry a person would recognise.
+      def payment_sources
+        Spree::CreditCard.with_deleted.
+          where(id: personal_card_ids(customer, email: customer.email)).map do |card|
+          {
+            brand: card.cc_type,
+            last_digits: card.last_digits,
+            name: card.name,
+            month: card.month,
+            year: card.year,
+            metadata: card.metadata.presence,
+            created_at: card.created_at&.iso8601
+          }
+        end
+      end
+
+      # Accounts the person linked to sign in with. The tokens are credentials
+      # rather than data about them, so only the provider and the identifier it
+      # knows them by are disclosed.
+      def connected_logins
+        customer.identities.map do |identity|
+          {
+            provider: identity.provider,
+            uid: identity.uid,
+            created_at: identity.created_at&.iso8601
+          }
+        end
+      end
+
+      def store_credits
+        customer.store_credits.map do |credit|
+          {
+            amount: credit.amount&.to_s,
+            amount_used: credit.amount_used&.to_s,
+            currency: credit.currency,
+            memo: credit.memo,
+            created_at: credit.created_at&.iso8601
+          }
+        end
+      end
+
+      def gift_cards
+        customer.gift_cards.map do |gift_card|
+          {
+            amount: gift_card.amount&.to_s,
+            amount_used: gift_card.amount_used&.to_s,
+            currency: gift_card.currency,
+            status: gift_card.status,
+            expires_at: gift_card.expires_at&.iso8601,
+            created_at: gift_card.created_at&.iso8601
+          }
+        end
+      end
+
+      def wishlists
+        # Through to the product: a variant's name delegates to it, so
+        # stopping at the variant costs a query per distinct item.
+        customer.wishlists.includes(wishlist_items: { variant: :product }).map do |wishlist|
+          {
+            name: wishlist.name,
+            is_private: wishlist.is_private,
+            created_at: wishlist.created_at&.iso8601,
+            items: wishlist.wishlist_items.map do |wished_item|
+              { sku: wished_item.variant&.sku, name: wished_item.variant&.name }
+            end
+          }
+        end
+      end
+
+      # Merchant-defined fields on the customer. Private ones are included:
+      # visibility governs what a storefront renders, not what the subject is
+      # entitled to see about themselves.
+      def custom_fields
+        return [] unless customer.respond_to?(:custom_fields)
+
+        customer.custom_fields.includes(:custom_field_definition).map do |field|
+          { key: field.key, value: field.value.to_s }
+        end
+      end
+
+      # A VAT or business registration on the account identifies the person
+      # (or their business) as surely as an address does.
+      def tax_identifiers
+        return [] unless customer.respond_to?(:tax_identifiers)
+
+        customer.tax_identifiers.map do |identifier|
+          {
+            kind: identifier.kind,
+            value: identifier.value,
+            validation_status: identifier.validation_status,
+            created_at: identifier.created_at&.iso8601
+          }
+        end
+      end
+
+      def companies
+        customer.company_memberships.includes(:company).map do |membership|
+          {
+            company: membership.company&.name,
+            created_at: membership.created_at&.iso8601
+          }
+        end
+      end
+
+      # Everything this person bought, however they were signed in at the time.
+      # Mirrors Spree::Customers::Anonymize#owned_purchases: a guest checkout
+      # leaves `customer_id` null, so an access response scoped to the account
+      # alone would omit history the store still holds — and that erasure will
+      # later wipe.
+      #
+      # @param model [Class]
+      # @return [ActiveRecord::Relation]
+      def owned_purchases(model)
+        purchases_about_person(model, customer, email: customer.email)
+      end
+
+      # @param address [Spree::Address, nil]
+      # @return [Hash, nil]
+      def address_hash(address)
+        return nil if address.nil?
+
+        {
+          label: address.label,
+          first_name: address.first_name,
+          last_name: address.last_name,
+          company: address.company,
+          address1: address.address1,
+          address2: address.address2,
+          city: address.city,
+          state_code: address.state_code,
+          state_name: address.state_name,
+          postal_code: address.postal_code,
+          country_code: address.country_code,
+          phone: address.phone,
+          alternative_phone: address.alternative_phone,
+          latitude: address.latitude,
+          longitude: address.longitude,
+          metadata: address.metadata.presence
+        }
+      end
+    end
+  end
+end

data/app/services/spree/data_requests/create.rb

@@ -0,0 +1,77 @@
+module Spree
+  module DataRequests
+    # Opens a data subject request and queues the work.
+    #
+    # An in-flight request is returned rather than duplicated. That is the
+    # rate limit: building an export is an unbounded read across a person's
+    # whole history, and a customer holding the button down should not be able
+    # to queue a hundred of them. It is also the honest answer — the request
+    # they already made is still being worked on.
+    class Create
+      prepend Spree::ServiceModule::Base
+
+      # @param store [Spree::Store]
+      # @param customer [Spree::Customer]
+      # @param kind [String] Spree::DataRequest::ACCESS or ERASURE
+      # @param requested_by [Object, nil] the staff actor; nil when the
+      #   subject asked for it themselves
+      # @param process [Boolean] whether to queue the work. False where the
+      #   caller fulfils the request itself — the admin export renders the file
+      #   inline for a waiting staffer, and queueing would additionally email
+      #   the customer a copy of something they did not ask for
+      # @return [Spree::ServiceModule::Result]
+      def call(store:, customer:, kind:, requested_by: nil, process: true)
+        # Nothing useful is left to answer with: an export would return the
+        # tombstone and email a link to an address that no longer receives,
+        # and a second erasure has nothing to erase.
+        if customer.anonymized?
+          data_request = Spree::DataRequest.new(customer: customer)
+          data_request.errors.add(:base, Spree.t('data_request_errors.already_anonymized'))
+          return failure(data_request)
+        end
+
+        data_request = nil
+        existing = nil
+
+        # Serialized on the customer row. A check-then-create leaves a window
+        # where two callers both see nothing in flight and both queue an export
+        # of the same person's whole history; taking the lock closes it without
+        # a partial unique index, which MySQL does not support.
+        customer.with_lock do
+          existing = in_flight_request(store: store, customer: customer, kind: kind)
+
+          unless existing
+            data_request = Spree::DataRequest.new(
+              store: store,
+              customer: customer,
+              kind: kind.to_s,
+              email: customer.email,
+              requested_by: requested_by
+            )
+            data_request.save
+          end
+        end
+
+        return success(existing) if existing
+        return failure(data_request) unless data_request.persisted?
+
+        # Enqueued after the lock is released: the job may start immediately,
+        # and it should not contend for the row this flow still holds.
+        Spree::DataRequests::ProcessJob.perform_later(data_request.prefixed_id) if process
+
+        success(data_request)
+      end
+
+      private
+
+      # Only the person's own requests. A staff member exporting from the admin
+      # opens their own row and answers it inline, and handing that back here
+      # would close the customer's request with a file they can never download.
+      def in_flight_request(store:, customer:, kind:)
+        Spree::DataRequest.where(store_id: store.id, customer_id: customer.id, kind: kind.to_s,
+                                 requested_by_id: nil).
+          in_progress.recent_first.first
+      end
+    end
+  end
+end

data/app/services/spree/deliveries/create.rb

@@ -0,0 +1,56 @@
+module Spree
+  module Deliveries
+    # Records a consignment on its owner: a parcel's tracking number, a
+    # forwarder's PRO or container number, or the number printed on a label
+    # that was just bought (docs/plans/6.0-shipping-labels-and-deliveries.md).
+    #
+    # The one write path for a delivery row — the +tracking:+ shortcut on
+    # Spree::Fulfillments::Fulfill / Update and the label workflows all come
+    # through here. A plain service: no hook has been earned yet.
+    class Create
+      prepend Spree::ServiceModule::Base
+
+      # @param owner [Spree::Fulfillment, Spree::Return]
+      # @param tracking_number [String] a carrier number, or a full tracking
+      #   link pasted whole — which then also becomes +tracking_url+
+      # @param carrier [String, nil] free text; detected from the number when omitted
+      # @param tracking_url [String, nil]
+      # @param service [String, nil]
+      # @param shipping_label [Spree::ShippingLabel, nil] the label that minted this delivery
+      # @param status [String] the carrier status to start at
+      # @param adopt [Boolean] when a delivery for this number already exists
+      #   on the owner, fill its blanks and return it rather than refusing.
+      #   A label binding the number the merchant typed by hand is the same
+      #   consignment; a merchant recording that number twice is not.
+      # @return [Spree::ServiceModule::Result] the delivery on success
+      def call(owner:, tracking_number:, carrier: nil, tracking_url: nil, service: nil,
+               shipping_label: nil, status: 'pending', adopt: false)
+        existing = adopt ? owner.deliveries.find_by(tracking_number: tracking_number.to_s.squish) : nil
+        delivery = existing || owner.deliveries.new(store: owner.store, tracking_number: tracking_number, status: status)
+
+        # Blanks are filled, never overwritten: whichever of the two arrived
+        # first said what it knew.
+        delivery.carrier = carrier.presence || delivery.carrier
+        delivery.service = service.presence || delivery.service
+        delivery.tracking_url = tracking_url.presence || delivery.tracking_url
+        delivery.shipping_label = shipping_label if shipping_label
+        delivery.tracking_url ||= delivery.tracking_number if delivery.pasted_link?
+
+        return failure(delivery) unless delivery.save
+
+        # A parcel that has not arrived makes a delivered fulfillment untrue.
+        recalculate(owner)
+
+        success(delivery)
+      end
+
+      private
+
+      def recalculate(owner)
+        return unless owner.is_a?(Spree::Fulfillment)
+
+        Spree.fulfillment_recalculate_delivery_service.call(fulfillment: owner)
+      end
+    end
+  end
+end

data/app/services/spree/deliveries/destroy.rb

@@ -0,0 +1,39 @@
+module Spree
+  module Deliveries
+    # Removes a hand-entered consignment that never went anywhere.
+    #
+    # Two things are not removable. A delivery minted by a label is the
+    # label's own record of what was bought, so the way out is refunding it,
+    # which drops the delivery when the parcel never moved. And a delivery
+    # that arrived is a fact about what happened — its arrival is what the
+    # returns window and the withdrawal period count from — so it stays, and
+    # a mistake is corrected by fixing the row rather than erasing it.
+    class Destroy
+      prepend Spree::ServiceModule::Base
+
+      # @param delivery [Spree::Delivery]
+      # @return [Spree::ServiceModule::Result]
+      def call(delivery:)
+        if delivery.shipping_label_id.present?
+          delivery.errors.add(:base, :has_label, message: Spree.t('deliveries.errors.has_label'))
+          return failure(delivery)
+        end
+
+        if delivery.delivered?
+          delivery.errors.add(:base, :delivered, message: Spree.t('deliveries.errors.delivered'))
+          return failure(delivery)
+        end
+
+        owner = delivery.owner
+        return failure(delivery) unless delivery.destroy
+
+        # Removing the last parcel still travelling completes the fulfillment.
+        if owner.is_a?(Spree::Fulfillment)
+          Spree.fulfillment_recalculate_delivery_service.call(fulfillment: owner)
+        end
+
+        success(delivery)
+      end
+    end
+  end
+end

data/app/services/spree/deliveries/upsert_primary.rb

@@ -0,0 +1,43 @@
+module Spree
+  module Deliveries
+    # The one-parcel shortcut behind `tracking:` on the fulfillment workflows
+    # and the tracking field in the dashboard: records the number as the
+    # fulfillment's primary consignment, or corrects the one it already has.
+    #
+    # A corrected number is a different parcel as far as the carrier is
+    # concerned, so its journey starts over.
+    class UpsertPrimary
+      prepend Spree::ServiceModule::Base
+
+      # @param fulfillment [Spree::Fulfillment]
+      # @param tracking [String, nil] a carrier number or a full tracking link;
+      #   blank is a no-op, so callers can pass an omitted parameter straight through
+      # @param carrier [String, nil] free text; detected from the number when omitted
+      # @return [Spree::ServiceModule::Result] the delivery, or nil when nothing was asked
+      def call(fulfillment:, tracking:, carrier: nil)
+        return success(nil) if tracking.blank?
+
+        primary = fulfillment.primary_delivery
+        return Spree.delivery_create_service.call(owner: fulfillment, tracking_number: tracking, carrier: carrier) if primary.nil?
+
+        number = tracking.to_s.squish
+        attributes = { tracking_number: number }
+        attributes[:carrier] = carrier if carrier.present?
+
+        # A corrected number is a different parcel: its journey starts over,
+        # and the carrier and link belonging to the old number go with it —
+        # otherwise a UPS badge and a UPS page survive onto a FedEx number.
+        corrected = number != primary.tracking_number
+        attributes = primary.correction_attributes(attributes)
+
+        return failure(primary) unless primary.update(attributes)
+
+        # A consignment that started over may have been the one holding the
+        # fulfillment at delivered.
+        Spree.fulfillment_recalculate_delivery_service.call(fulfillment: fulfillment) if corrected
+
+        success(primary)
+      end
+    end
+  end
+end

data/app/services/spree/fulfillments/recalculate_delivery.rb

@@ -0,0 +1,62 @@
+module Spree
+  module Fulfillments
+    # Keeps a fulfillment's `delivered` honest about its consignments.
+    #
+    # A fulfillment travels as one parcel most of the time, but not always: a
+    # single gym rack is one line item in three boxes, each with its own
+    # tracking number and its own carrier journey. So `delivered` is not a
+    # flag anyone sets — it is the answer to "has every parcel arrived?",
+    # recomputed whenever that answer could have changed: a carrier reports an
+    # arrival, a merchant adds a fourth box, or removes one.
+    #
+    # It moves in both directions. Adding a parcel to a fulfillment already
+    # marked delivered steps it back to `fulfilled`, because the goods are out
+    # and not all of them have landed — saying otherwise would misdate the
+    # returns window, which counts from arrival.
+    #
+    # A fulfillment with no consignments at all is left alone. Pickup, hand
+    # delivery and freight with no carrier feed are delivered by staff saying
+    # so, and there is nothing here to compute from.
+    class RecalculateDelivery
+      prepend Spree::ServiceModule::Base
+
+      # @param fulfillment [Spree::Fulfillment]
+      # @param notify_customer [Boolean] whether completing the delivery
+      #   emails the customer
+      # @return [Spree::ServiceModule::Result] the fulfillment
+      def call(fulfillment:, notify_customer: true)
+        # The caller has usually just written a delivery through another
+        # object, so the loaded collection may still hold the old picture.
+        fulfillment.deliveries.reset
+        deliveries = fulfillment.deliveries
+
+        return success(fulfillment) if deliveries.empty?
+
+        if deliveries.undelivered.exists?
+          return success(fulfillment) unless fulfillment.delivered?
+
+          return reopen(fulfillment)
+        end
+
+        return success(fulfillment) unless fulfillment.can_mark_delivered?
+
+        result = Spree.fulfillment_mark_delivered_workflow.call(
+          fulfillment: fulfillment,
+          delivered_at: deliveries.maximum(:delivered_at),
+          notify_customer: notify_customer
+        )
+        result.success? ? success(fulfillment.reload) : failure(fulfillment, result.error.to_s)
+      end
+
+      private
+
+      # Back to handed-over. `delivered_at` is cleared with it: it stamps when
+      # the whole fulfillment arrived, and that is no longer true.
+      def reopen(fulfillment)
+        fulfillment.update!(status: 'fulfilled', delivered_at: nil)
+        fulfillment.order&.update_statuses!
+        success(fulfillment)
+      end
+    end
+  end
+end