spree_core 6.0.0.rc3 → 6.0.0.rc5

data/app/services/spree/carts/split_by_seller.rb

@@ -34,10 +34,15 @@ module Spree
       # recorded about the purchase (copied from the cart), so every child gets
       # the same hash — and so does the group. Once split, each order's
       # metadata is its own: edits never propagate between siblings.
+      #
+      # `applied_tax_exemptions` rides along, or a sibling resolves again and
+      # takes override ids that match nothing it owns. Line items keep their ids
+      # here; a divided fulfillment and its money rows do not, so an override
+      # naming one is stale — latent while nothing supplies overrides.
       CARRIED_TO_SIBLING = %w[
         email currency locale market_id channel_id company_id
         customer_id token accept_marketing preferred_stock_location_id
-        customer_note last_ip_address po_number metadata
+        customer_note last_ip_address po_number metadata applied_tax_exemptions
       ].freeze
 
       # @param order [Spree::Order] the paid draft order, adopted as the

data/app/services/spree/carts/update.rb

@@ -28,10 +28,11 @@ module Spree
         success(cart)
       rescue ActiveRecord::RecordNotFound
         raise
-      rescue Spree::Pricing::PriceResolution::ProviderUnavailable => e
-        # A strict store could not confirm a price. The transaction has rolled
-        # back, so the address change is not committed either — better than
-        # saving a destination whose prices nobody stood behind.
+      rescue Spree::Pricing::PriceResolution::ProviderUnavailable, Spree::Tax::ProviderError => e
+        # A strict store could not confirm a price, or the tax engine did not
+        # produce tax. The transaction has rolled back, so the address change is
+        # not committed either — better than saving a destination whose prices
+        # or tax nobody stood behind.
         #
         # The in-memory cart still holds the rolled-back attributes, though, so
         # a caller that renders the object it passed in would show the customer
@@ -48,7 +49,7 @@ module Spree
         end
         cart.warnings |= warnings if warnings.present?
 
-        failure(cart, I18n.t('spree.cart_line_item.pricing_unavailable'))
+        failure(cart, { code: unavailable_code_for(e), message: unavailable_message_for(e) })
       rescue ActiveRecord::RecordInvalid => e
         failure(cart, e.record.errors.full_messages.to_sentence)
       rescue StandardError => e
@@ -205,10 +206,7 @@ module Spree
       end
 
       def resolve_address_id(prefixed_id)
-        return unless cart.customer
-
-        decoded = Spree::Address.decode_prefixed_id(prefixed_id)
-        decoded ? cart.customer.addresses.find_by(id: decoded)&.id : nil
+        cart.selectable_address(prefixed_id)&.id
       end
 
       def assign_market
@@ -229,6 +227,29 @@ module Spree
         end
       end
 
+      # Three ways an external service can leave a sale unpriced, and a
+      # customer can only act on what they are told. A refused calculation
+      # carries the engine's own words, because "the postcode is not valid for
+      # that state" is something they can fix and "please try again" is not.
+      # The same split the API's own handler makes: a refusal names something
+      # to fix, an outage is worth retrying, and a price that could not be
+      # confirmed is neither tax case.
+      def unavailable_code_for(error)
+        case error
+        when Spree::Tax::CalculationRefused then 'tax_calculation_refused'
+        when Spree::Tax::ProviderError then 'tax_provider_unavailable'
+        else 'provider_unavailable'
+        end
+      end
+
+      def unavailable_message_for(error)
+        case error
+        when Spree::Tax::CalculationRefused then error.message.to_s
+        when Spree::Tax::ProviderError then I18n.t('spree.cart_line_item.tax_unavailable')
+        else I18n.t('spree.cart_line_item.pricing_unavailable')
+        end
+      end
+
       # Three-way dispatch on the cart→checkout transition:
       # entering checkout → Reserve, mid-checkout mutation → Extend, reverting to cart → Release.
       # A failed Reserve raises so the enclosing transaction rolls back and the
@@ -256,10 +277,13 @@ module Spree
         else
           cart.recalculate_totals!
         end
-      rescue Spree::Pricing::PriceResolution::ProviderUnavailable
+      rescue Spree::Pricing::PriceResolution::ProviderUnavailable, Spree::Tax::ProviderError
         # Deliberately not swallowed like the rest: a strict store refusing to
         # price must roll the whole update back, so `call` sees it and the
-        # address change does not commit around unconfirmed prices.
+        # address change does not commit around unconfirmed prices. A tax engine
+        # that cannot answer is the same problem one column over — swallowing it
+        # showed the customer a total with tax missing and saved the address
+        # anyway, so the mistake only surfaced when they tried to pay.
         raise
       rescue StandardError => e
         Rails.error.report(e, context: { order_id: cart.id }, source: 'spree.checkout')

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

@@ -0,0 +1,37 @@
+module Spree
+  module DataRequests
+    # Confirms a request the customer raised, from the link emailed to the
+    # address it names, and queues the work.
+    #
+    # Confirming again is answered with the request as it stands, so a second
+    # click on the same link changes nothing.
+    class Confirm
+      prepend Spree::ServiceModule::Base
+
+      # @param data_request [Spree::DataRequest]
+      # @return [Spree::ServiceModule::Result] the confirmed request
+      def call(data_request:)
+        newly_confirmed = false
+
+        data_request.with_lock do
+          newly_confirmed = data_request.confirmable?
+
+          if newly_confirmed
+            data_request.update!(status: 'pending')
+          elsif data_request.awaiting_confirmation?
+            data_request.update!(status: 'lapsed')
+          end
+        end
+
+        if data_request.lapsed?
+          data_request.errors.add(:base, I18n.t('spree.data_request_errors.confirmation_invalid'))
+          return failure(data_request)
+        end
+
+        Spree::DataRequests::ProcessJob.perform_later(data_request.prefixed_id) if newly_confirmed
+
+        success(data_request)
+      end
+    end
+  end
+end

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

@@ -7,9 +7,15 @@ module Spree
     # 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.
+    #
+    # A request the customer raised themselves waits for confirmation from its
+    # email address instead of being queued, because it reaches guest orders
+    # placed at that address. Asking again while it waits sends the email again.
     class Create
       prepend Spree::ServiceModule::Base
 
+      CONFIRMATION_EVENT = 'data_request.confirmation_requested'.freeze
+
       # @param store [Spree::Store]
       # @param customer [Spree::Customer]
       # @param kind [String] Spree::DataRequest::ACCESS or ERASURE
@@ -19,8 +25,12 @@ module Spree
       #   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
+      # @param confirm_by_email [Boolean] hold the request until it is
+      #   confirmed from its email address; true for the customer's own requests
+      # @param redirect_url [String, nil] the storefront page the confirmation
+      #   link opens, already checked against the store's allowed origins
       # @return [Spree::ServiceModule::Result]
-      def call(store:, customer:, kind:, requested_by: nil, process: true)
+      def call(store:, customer:, kind:, requested_by: nil, process: true, confirm_by_email: false, redirect_url: nil)
         # 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.
@@ -38,7 +48,9 @@ module Spree
         # 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)
+          lapse_unconfirmed_requests(store: store, customer: customer, kind: kind, staff_request: !confirm_by_email)
+          existing = in_flight_request(store: store, customer: customer, kind: kind,
+                                       include_unconfirmed: confirm_by_email)
 
           unless existing
             data_request = Spree::DataRequest.new(
@@ -46,20 +58,27 @@ module Spree
               customer: customer,
               kind: kind.to_s,
               email: customer.email,
-              requested_by: requested_by
+              requested_by: requested_by,
+              status: confirm_by_email ? 'awaiting_confirmation' : 'pending'
             )
             data_request.save
           end
         end
 
-        return success(existing) if existing
-        return failure(data_request) unless data_request.persisted?
+        return failure(data_request) if data_request && !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
+        request = existing || data_request
 
-        success(data_request)
+        # Both happen after the lock is released: the job may start at once and
+        # should not contend for the row this flow holds, and the email must
+        # not go out before the row is committed.
+        if request.awaiting_confirmation?
+          request_confirmation(request, redirect_url: redirect_url)
+        elsif data_request && process
+          Spree::DataRequests::ProcessJob.perform_later(data_request.prefixed_id)
+        end
+
+        success(request)
       end
 
       private
@@ -67,10 +86,39 @@ module Spree
       # 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
+      # A request still waiting for confirmation is returned only to the
+      # customer: staff have checked who they are dealing with, so theirs
+      # proceeds on its own row (see lapse_unconfirmed_requests).
+      def in_flight_request(store:, customer:, kind:, include_unconfirmed:)
+        requests = Spree::DataRequest.where(store_id: store.id, customer_id: customer.id, kind: kind.to_s,
+                                            requested_by_id: nil)
+        open_requests = include_unconfirmed ? requests.in_progress.or(requests.confirmable) : requests.in_progress
+
+        open_requests.recent_first.first
+      end
+
+      # Lapses what can no longer be confirmed: requests past the window, and
+      # requests naming an address the account has since moved away from, so
+      # asking again emails the current address. A staff request of the same
+      # kind replaces the customer's unconfirmed one, which would otherwise
+      # run the same work a second time once confirmed.
+      def lapse_unconfirmed_requests(store:, customer:, kind:, staff_request:)
+        unconfirmed = Spree::DataRequest.where(store_id: store.id, customer_id: customer.id).awaiting_confirmation
+        stale = unconfirmed.past_confirmation_window.or(unconfirmed.where.not(email: customer.email))
+        stale = stale.or(unconfirmed.where(kind: kind.to_s)) if staff_request
+
+        stale.find_each { |data_request| data_request.update!(status: 'lapsed') }
+      end
+
+      # The token travels in a credential event, which reaches only webhook
+      # endpoints that name it and keeps the token out of the delivery log.
+      def request_confirmation(data_request, redirect_url:)
+        payload = data_request.event_payload_for(
+          CONFIRMATION_EVENT,
+          confirmation_token: data_request.generate_token_for(:confirmation),
+          redirect_url: redirect_url.presence
+        )
+        data_request.publish_event(CONFIRMATION_EVENT, payload)
       end
     end
   end

data/app/services/spree/email_templates/preview.rb

@@ -23,8 +23,11 @@ module Spree
       # @param email_key [String, nil] for the layout or a partial, the email to show it in
       # @param strict [Boolean] whether an unknown variable raises
       # @param branding [Hash] unsaved branding values (see Spree::Emails::Branding)
+      # @param mailer_logo_signed_id [String, nil] the signed id of an unsaved, uploaded email logo
+      # @param mailer_logo_cleared [Boolean] whether the email logo is previewed as removed
       def initialize(store:, key:, locale: Spree::EmailTemplate::ANY_LOCALE, subject: nil, body: nil,
-                     record_id: nil, email_key: nil, strict: false, branding: {})
+                     record_id: nil, email_key: nil, strict: false, branding: {}, mailer_logo_signed_id: nil,
+                     mailer_logo_cleared: false)
         @store = store
         @key = key
         @locale = locale.presence || Spree::EmailTemplate::ANY_LOCALE
@@ -34,16 +37,20 @@ module Spree
         @email_key = email_key
         @strict = strict
         @branding = branding
+        @mailer_logo_signed_id = mailer_logo_signed_id
+        @mailer_logo_cleared = mailer_logo_cleared
       end
 
       # @return [Spree::Emails::RenderedEmail]
       # @raise [Spree::EmailTemplates::NoSampleRecord] when the store has no record to build the sample from
+      # @raise [ActiveRecord::RecordInvalid] when the unsaved logo is one saving the store would refuse
+      # @raise [ActiveSupport::MessageVerifier::InvalidSignature] when the unsaved logo's signed id is not valid
       def call
         sample = email.sample_class.new(store: @store, record_id: @record_id)
 
         in_locale do
-          renderer = Spree::Emails::Renderer.new(resolver: resolver, store: @store, currency: sample.currency, strict: @strict,
-                                                 branding: @branding)
+          renderer = Spree::Emails::Renderer.new(resolver: resolver, store: email_store, currency: sample.currency,
+                                                 strict: @strict, branding: @branding)
           sample_variables = sample.variables
           @variables = renderer.variables(sample_variables)
           @rendered = renderer.render(resolver.find(email.key), sample_variables)
@@ -66,6 +73,20 @@ module Spree
         Spree.editable_email_templates[@key] || raise(ArgumentError, "#{@key} is not an editable email template")
       end
 
+      # The store as the email shows it. An unsaved logo upload or removal is
+      # applied to a copy that is never saved, and checked as saving the store
+      # checks it, so the preview never shows a logo the Save button refuses.
+      def email_store
+        return @store if @mailer_logo_signed_id.nil? && !@mailer_logo_cleared
+
+        @email_store ||= @store.class.find(@store.id).tap do |store|
+          store.mailer_logo = @mailer_logo_cleared ? nil : @mailer_logo_signed_id
+          store.validate
+          (store.errors.attribute_names - [:mailer_logo]).each { |attribute| store.errors.delete(attribute) }
+          raise ActiveRecord::RecordInvalid, store if store.errors.any?
+        end
+      end
+
       def resolver
         @resolver ||= Spree::Emails::TemplateResolver.for_mailers(store: @store, locale: language, drafts: drafts)
       end

data/app/services/spree/seeds/store_resources.rb

@@ -18,6 +18,7 @@ module Spree
         Spree::Events.disable do
           ActiveRecord::Base.no_touching do
             TaxCategories.call(store: store)
+            TaxExemptionReasons.call(store: store)
             Channels.call(store: store)
             Roles.call(store: store)
             DigitalDelivery.call(store: store)

data/app/services/spree/seeds/tax_exemption_reasons.rb

@@ -0,0 +1,28 @@
+module Spree
+  module Seeds
+    # The reasons a business can give for buying without tax. Neutral codes
+    # that Spree's own engine keeps for reference; a store using an engine
+    # that reads them (Avalara) changes each code to that engine's.
+    class TaxExemptionReasons
+      prepend Spree::ServiceModule::Base
+      include StoreScoped
+
+      REASONS = {
+        'RESALE' => 'Resale',
+        'GOVERNMENT' => 'Government',
+        'CHARITABLE' => 'Charitable organization',
+        'EDUCATIONAL' => 'Educational institution',
+        'MANUFACTURING' => 'Manufacturing',
+        'AGRICULTURAL' => 'Agricultural'
+      }.freeze
+
+      private
+
+      def seed(store)
+        REASONS.each do |code, name|
+          store.tax_exemption_reasons.find_or_create_by_code_or_name!(code: code, name: name)
+        end
+      end
+    end
+  end
+end

data/app/services/spree/tax/resolve_exemptions.rb

@@ -29,9 +29,18 @@ module Spree
         return success([]) if company.nil? || address.nil?
 
         success(
-          company.tax_exemption_certificates.active.for_address(address).map do |certificate|
+          company.tax_exemption_certificates.active.for_address(address).includes(:tax_exemption_reason).filter_map do |certificate|
+            reason = certificate.tax_exemption_reason
+            # A certificate recorded before reasons existed keeps its old code
+            # until `spree:upgrade:tax_exemption_reasons` links it. One with
+            # neither (its reason row removed outside the app) is skipped
+            # rather than failing tax for every order of the company.
+            reason_code = reason&.code || certificate.reason_code
+            next if reason_code.blank?
+
             Spree::TaxExemption.new(
-              reason_code: certificate.reason_code,
+              reason_code: reason_code,
+              reason_name: reason&.name,
               certificate_number: certificate.certificate_number,
               country_code: certificate.country_code,
               state_code: certificate.state_code

data/app/services/spree/update_check.rb

@@ -34,9 +34,16 @@ module Spree
     LARGEST_BUCKET = '100k+'.freeze
 
     class << self
+      # Always false in the test environment and on CI servers (which set
+      # +CI+), so no test run ever reaches spreecloud.io; specs stub the
+      # request instead.
+      #
       # @return [Boolean] false when the operator turned the check off
       def enabled?
-        Spree::Config.update_check_enabled && !env_flag?('SPREE_UPDATE_CHECK_DISABLED')
+        !Rails.env.test? &&
+          !env_flag?('CI') &&
+          Spree::Config.update_check_enabled &&
+          !env_flag?('SPREE_UPDATE_CHECK_DISABLED')
       end
 
       # When false, the check still runs but sends the running version only.

data/app/tools/spree/agent_tools/create_export.rb

@@ -0,0 +1,116 @@
+module Spree
+  module AgentTools
+    # Exports records to a CSV the merchant can download.
+    #
+    # Mutating not because it changes the store — it does not — but because
+    # it produces a file of store data and emails a link to it. That leaves
+    # the building, so a merchant decides, not the model.
+    class CreateExport < Spree::AgentTool
+      tool_name 'create_export'
+      description 'Export records to a CSV file. Say which kind of records and, ' \
+                  'optionally, the same filters search_resources accepts. The merchant ' \
+                  'approves before the file is generated.'
+      # Exports are gated on the READ scope of what is being exported — the
+      # Admin API treats an export as a read, because that is what it is. That
+      # is a per-resource question, so it is answered in `call` rather than
+      # here: a class-level key would hide the tool from a caller who may
+      # export orders but not products.
+
+      # Exports whose rows carry a bearer instrument — a code that spends
+      # money for whoever reads it. Refused outright rather than stripped,
+      # because an export of gift cards without their codes answers nothing
+      # the merchant asked for. `Spree::Mcp::Exports` reads this list too, so
+      # a file made before this existed stays unreadable.
+      BEARER_EXPORTS = %w[gift_cards coupon_codes].freeze
+
+      permission nil
+      mutating!
+
+      param :resource, description: 'What to export: products, orders, customers',
+                       required: true
+      param :filters, type: :object,
+                      description: 'Optional Ransack filters, e.g. {"status_eq": "active"}'
+
+      def call(resource:, filters: nil)
+        export_class = export_class_for(resource)
+        return unknown_resource(resource) if export_class.nil?
+
+        required = "read_#{export_class.required_scope}"
+        unless context.holds?(required)
+          return { error: "You do not have permission to export #{resource.to_s.tr('_', ' ')}." }
+        end
+
+        # Refused here rather than at read, so the merchant is not left with a
+        # generated file of live codes waiting to be collected.
+        if Spree::AgentTools::CreateExport::BEARER_EXPORTS.include?(resource.to_s)
+          return { error: "#{resource.to_s.tr('_', ' ').capitalize} carry codes that spend money for " \
+                          'whoever reads them, so they cannot be exported here. Download them from ' \
+                          'the dashboard instead.' }
+        end
+
+        export = export_class.new(
+          store: context.store,
+          # For a signed-in admin the export builds an ability from this user,
+          # so the file holds exactly the records that admin could see,
+          # record-level rules included. For an API key there is no user and
+          # no ability: the scope check above is the whole filter, which is
+          # how the Admin API treats key requests everywhere else.
+          user: context.user,
+          format: 'csv',
+          search_params: filters.presence
+        )
+
+        refusal = unauthorized(:create, export)
+        return refusal if refusal
+
+        # Saving publishes `export.created`, which is what actually enqueues
+        # generation. (`generate_async` hands a raw id to a job that expects a
+        # prefixed one — the subscriber is the working path.)
+        return { error: export.errors.full_messages.to_sentence } unless export.save
+
+        {
+          ok: true,
+          id: export.prefixed_id,
+          resource: resource.to_s,
+          # Generation is a background job, so there is no file yet. Naming
+          # the tool that finishes the job keeps the model from sending the
+          # merchant to the dashboard for something it can fetch itself.
+          # Naming the MCP resource matters: a client that can read one will
+          # otherwise never learn the file is there, and the model reports a
+          # download path to a merchant instead of reading the rows itself.
+          resource_uri: "spree+export://#{export.prefixed_id}",
+          message: 'The export is being prepared. Once it is ready you can read its contents ' \
+                   "from the MCP resource spree+export://#{export.prefixed_id}, or call " \
+                   "get_resource (resource: \"exports\", id: \"#{export.prefixed_id}\") for its " \
+                   'status and a download_url to hand the merchant.'
+        }
+      end
+
+      def summary(arguments)
+        label = arguments[:resource].to_s.tr('_', ' ')
+        return "Export all #{label}" if arguments[:filters].blank?
+
+        filters = arguments[:filters].keys.map { |key| key.to_s.tr('_', ' ') }.join(', ')
+        "Export #{label} filtered by #{filters}"
+      end
+
+      private
+
+      # Only the export kinds Spree actually ships, resolved by name rather
+      # than constantized from model input.
+      def export_class_for(resource)
+        key = resource.to_s.downcase
+        Spree::Export.descendants.find do |klass|
+          klass.name.demodulize.underscore == key
+        end
+      end
+
+      def unknown_resource(resource)
+        {
+          error: "Cannot export #{resource.inspect}",
+          available: Spree::Export.descendants.map { |k| k.name.demodulize.underscore }.sort
+        }
+      end
+    end
+  end
+end

data/app/tools/spree/agent_tools/create_import.rb

@@ -0,0 +1,117 @@
+module Spree
+  module AgentTools
+    # Starts a CSV import from a file the merchant provided.
+    #
+    # Gated on the WRITE scope of what is being imported, computed per call —
+    # a customers import needs `write_customers`, a products import
+    # `write_products`. A single class-level key could not say that, which is
+    # why the resource reached the map read-only; `create_export` answers the
+    # same question the same way.
+    #
+    # Creating the import reads the file's header row and proposes a column
+    # mapping. Nothing is written to the catalog until that mapping is
+    # confirmed, so this is the safe half of the wizard: the merchant still
+    # sees what the columns were taken to mean before any row lands.
+    class CreateImport < Spree::AgentTool
+      tool_name 'create_import'
+      description 'Start a CSV import from a file the merchant provided. Call upload_file ' \
+                  'first and pass the file_id it returns. The columns are read and a mapping ' \
+                  'proposed; no records change until the mapping is confirmed.'
+      # Per-resource, answered in `call` — a class-level key would hide the
+      # tool from a caller who may import one kind of record but not another.
+      permission nil
+      mutating!
+
+      param :resource, description: 'What the file holds: products, customers, purchase_orders',
+                       required: true
+      param :file_id, description: 'The file_id upload_file returned', required: true
+
+      def call(resource:, file_id:)
+        import_class = import_class_for(resource)
+        return unknown_resource(resource) if import_class.nil?
+
+        required = "write_#{import_class.required_scope}"
+        unless context.holds?(required)
+          return { error: "You do not have permission to import #{resource.to_s.tr('_', ' ')}." }
+        end
+
+        start(import_class, resource, file_id)
+      end
+
+      def summary(arguments)
+        "Start a #{arguments[:resource].to_s.tr('_', ' ')} import"
+      end
+
+      private
+
+      def start(import_class, resource, file_id)
+        owner = importing_user
+        return { error: no_user_error } if owner.nil?
+
+        import = import_class.new(store: context.store, user: owner)
+        import.attachment = file_id
+
+        refusal = unauthorized(:create, import)
+        return refusal if refusal
+        return { error: import.errors.full_messages.to_sentence } unless import.save
+
+        mapping = Spree.import_start_mapping_workflow.call(import: import)
+        return { error: mapping_failure(mapping, import) } unless mapping.success?
+
+        {
+          ok: true,
+          id: import.prefixed_id,
+          resource: resource.to_s,
+          status: import.reload.status,
+          # The mapping is the point of this step: the model should read it
+          # back and tell the merchant what the columns were taken to mean
+          # before anything is written.
+          next_step: "Call describe_import_mapping with id #{import.prefixed_id} to see the " \
+                     'columns, then confirm it to run the import.',
+          dashboard_path: ResourceMap.find('imports')&.dashboard_path_for(import)
+        }
+      rescue ::CSV::MalformedCSVError, EncodingError => e
+        { error: "That file could not be read as CSV: #{e.message}" }
+      rescue ActiveSupport::MessageVerifier::InvalidSignature, ActiveRecord::RecordNotFound
+        { error: "#{file_id.inspect} is not a file this store uploaded. Call upload_file first." }
+      rescue ActiveStorage::FileNotFoundError
+        { error: 'That upload did not finish — its bytes are missing. Upload the file again.' }
+      end
+
+      def mapping_failure(result, import)
+        error = result.error
+        message = error.try(:value).is_a?(String) ? error.value : error.to_s
+
+        message.presence || import.processing_errors.presence || 'The file could not be mapped.'
+      end
+
+      # An import belongs to a person — it emails them when it finishes and
+      # its failed rows are theirs to retry. A grant carries the admin who
+      # approved it; a standing key carries whoever minted it, which is the
+      # same fallback the Admin API uses.
+      def importing_user
+        return context.user if context.user.present?
+
+        creator = context.api_key&.created_by
+        creator if creator.is_a?(Spree.admin_user_class)
+      end
+
+      def no_user_error
+        'An import has to belong to a staff member, and this credential names none. ' \
+          'Connect an agent through the dashboard, or start the import there.'
+      end
+
+      def import_class_for(resource)
+        key = resource.to_s.downcase
+        Spree::Import.available_types.find { |klass| klass.name.demodulize.underscore == key }
+      end
+
+      def unknown_resource(resource)
+        {
+          error: "Cannot import #{resource.inspect}.",
+          available: Spree::Import.available_types.map { |k| k.name.demodulize.underscore }.sort
+        }
+      end
+    end
+  end
+end